\section{Introduction} \subsection{Nouveautés depuis la version 3.0} Depuis la version 3.0, \textbf{toutes} les données relatives au paquet \emph{luadraw} sont encapsulées dans un même espace de noms, celui-ci s'appelle \textbf{luadraw} (c'est une table). Ceci a pour conséquence que les données sont accessibles uniquement avec la notation pointée, plus précisément : \begin{enumerate} \item la classe \emph{graph} devient \emph{luadraw.graph}, \item la classe \emph{cpx} (nombres complexes) devient \emph{luadraw.cpx}, \item la classe \emph{graph3d} devient \emph{luadraw.graph3d}, \item la classe \emph{pt3d} (points 3D) devient \emph{luadraw.pt3d}, \item toutes les variables globales, toutes les fonctions non graphiques sont dans l'espace de nommage \emph{luadraw}, sauf quelques exceptions propres aux nombres complexes qui sont passées dans la classe \emph{cpx}, et quelques exceptions propres aux points 3D qui sont passées dans la classe \emph{pt3d}, \item par contre il n'y a pas de changement pour les méthodes graphiques puisqu'elles étaient déjà encapsulées dans les classes \emph{graph} et \emph{graph3d}. \end{enumerate} Le langage Lua n'autorise pas la factorisation de l'espace de noms, il faut donc réellement utiliser la notation pointée, mais heureusement on peut se créer des raccourcis (ou alias), par exemple : \begin{Luacode} local ld = luadraw -- alias sur l'espace de nommage local cpx, pt3d = ld.cpx, ld.pt3d -- raccourcis pour les classes cpx et pt3d local Z, M, i = cpx.Z, pt3d.M, cpx.I -- raccourcis vers les fonctions Z et M et le complexe i local Origin, vecI, vecJ, vecK = pt3d.Origin, pt3d.vecI, pt3d.vecJ, pt3d.vecK local g = ld.graph3d:new{} ... \end{Luacode} Du fait de ce changement majeur, les scripts \emph{luadraw} des versions antérieures \textbf{ne sont plus compilables directement}, ils doivent être adaptés à cette nouvelle version. Mais avec des raccourcis, les changements sont minimes. \paragraph{Autre nouveauté} : l'environnement \emph{luadraw} fait appel à un environnement \emph{luacode} (et non plus \emph{luacode*}) ce qui permet d'introduire des macros \TeX{} dans le code \emph{Lua}, on peut donc mettre les raccourcis les plus fréquents dans une macro et l'utiliser dans ses codes \emph{luadraw}, par exemple : \begin{TeXcode} \documentclass{article} \usepackage[3d]{luadraw} \newcommand*{\shortcuts}{% local ld = luadraw local cpx, pt3d = ld.cpx, ld.pt3d local Z, M, i = cpx.Z, pt3d.M, cpx.I local Origin, vecI, vecJ, vecK = pt3d.Origin, pt3d.vecI, pt3d.vecJ, pt3d.vecK }% \begin{document} \begin{luadraw}{name=test} \shortcuts local g = ld.graph3d:new{} local P = ld.polyreg(0, Z(2,3), 5) g:Dpolyline(P, true, "red,line width=1.2pt") local Q = ld.map(pt3d.toPoint3d, P) P = ld.pyramid(Q, M(0,0,4)) g:Dpoly(P, {color="blue", opacity=0.6}) g:Show() \end{luadraw} \end{document} \end{TeXcode} L'environnement étoilé \emph{luadraw*} quant à lui, fait appel à un environnement \emph{luacode*}, dans ce cas il n'y a aucune ingérence de \TeX{} dans le code Lua. \paragraph{NB} : dans toute la suite de cette documentation nous utiliserons les raccourcis suivants : \begin{Luacode} local ld = luadraw -- alias sur l'espace de nommage local cpx = ld.cpx -- raccourci pour la classe cpx local pt3d = ld.pt3d -- raccourci pour la classe pt3d \end{Luacode} \subsection{Prérequis} \begin{itemize} \item Dans le préambule, il faut déclarer le package \luadrawenv : \verb|\usepackage[options globales]{luadraw}| \item La compilation se fait avec LuaLatex \textbf{exclusivement}. \item Les couleurs dans l'environnement \emph{luadraw} sont des chaînes de caractères qui doivent correspondre à des couleurs connues de TikZ. Il est fortement conseillé d'utiliser le package \emph{xcolor} avec l'option \emph{svgnames}. \end{itemize} Quelque soient les options globales choisies, ce paquet charge le module \emph{luadraw\_graph2d.lua} qui définit la classe \emph{ld.graph}, et fournit l'environnement \emph{luadraw} qui permet de faire des graphiques en Lua. Pour pouvoir faire des graphiques en 3D il faut charger en plus la classe \emph{ld.graph3d} grâce à l'option globale \opt{3d} :\par \hfil\verb|\usepackage[3d]{luadraw}|.\hfil \paragraph{Options globales du paquet} : \opt{noexec}, \opt{3d} et \opt{cachedir=}. \begin{itemize} \item \opt{noexec} : lorsque cette option globale est mentionnée la valeur par défaut de l'option \emph{exec} pour l'environnement \emph{luadraw} sera false (et non plus true). \item \opt{3d} : lorsque cette option globale est mentionnée, le module \emph{luadraw\_graph3d.lua} est également chargé. Celui-ci définit en plus la classe \emph{ld.graph3d} (qui s'appuie sur la classe \emph{ld.graph}) pour des dessins en 3D. \item \opt{cachedir=} : par défaut les fichiers créés sont enregistrés dans le dossier \emph{\_luadraw} qui est un sous-dossier du dossier courant (contenant le document maître). Ce dossier peut être changé avec l'option \opt{cachedir}, par exemple \opt{cachedir=\{tikz\}}. \end{itemize} \noindent\textbf{NB} : dans ce chapitre nous ne parlerons pas de l'option \opt{3d}. Celle-ci fait l'objet du chapitre suivant. Nous ne parlerons donc que de la version 2D. Lorsqu'un graphique est terminé il est exporté au format TikZ, donc ce paquet charge également le paquet TikZ ainsi que les librairies : \begin{itemize} \item\emph{patterns} \item\emph{plotmarks} \item\emph{arrows.meta} \item\emph{decorations.markings} \end{itemize} Les graphiques sont créés dans un environnement \luadrawenv, celui-ci appelle \emph{luacode}, c'est donc du \textbf{langage Lua} qu'il faut utiliser dans cet environnement : \begin{TeXcode} \begin{luadraw}{ name = , exec = true/false, auto = true/false } local ld = luadraw -- création d'un nouveau graphique en lui donnant un nom local (cette ligne est un commentaire) local g = ld.graph:new{ window={x1,x2,y1,y2 [,xscale,yscale]}, margin={top,right,bottom,left}, size={width,height,ratio}, bg="color", border=true/false } -- construction du graphique g instructions graphiques en langage Lua ... -- affichage du graphique g et sauvegarde dans le fichier .tkz g:Show() -- ou bien sauvegarde uniquement dans le fichier .tkz g:Save() \end{luadraw} \end{TeXcode} \paragraph{Sauvegarde du fichier \emph{*.tkz}} : le graphique est exporté au format TikZ dans un fichier (avec l'extension \emph{tkz}), par défaut celui-ci est sauvegardé dans le dossier \emph{\_luadraw} qui est un sous-dossier du dossier courant (contenant le document maître), mais il est possible d'imposer un chemin vers un autre sous-dossier avec l'option globale \opt{cachedir=\ldots}. \subsection{Options de l'environnement \luadrawenv} Celles-ci sont : \begin{itemize} \item \opt{name=\ldots{}} : permet de donner un nom au fichier TikZ produit, on donne un nom sans extension (celle-ci sera automatiquement ajoutée, c'est \emph{.tkz}). Si cette option est omise, alors il y a un nom par défaut, qui est le nom du fichier maître suivi d'un numéro. \item \opt{exec=true/false} : permet d'exécuter ou non le code Lua compris dans l'environnement. Par défaut cette option vaut true, \textbf{SAUF} si l'option globale \opt{noexec} a été mentionnée dans le préambule avec la déclaration du paquet. Lorsqu'un graphique complexe qui demande beaucoup de calculs est au point, il peut être intéressant de lui ajouter l'option \opt{exec=false}, cela évitera les recalculs de ce même graphique pour les compilations à venir. \item \opt{auto=true/false} : permet d'inclure ou non automatiquement le fichier TikZ en lieu et place de l'environnement \luadrawenv lorsque l'option \opt{exec} est à \false. Par défaut l'option \opt{auto} vaut \true. \end{itemize} \subsection{La classe ld.cpx (complexes)} Rappel : nous utilisons l'alias \code{local cpx = ld.cpx}. Elle est automatiquement chargée par le module \emph{luadraw\_graph2d} et donc au chargement du paquet \luadrawenv. Cette classe permet de manipuler les nombres complexes et de faire les calculs habituels. On crée un complexe avec la fonction \cmd{cpx.Z(a, b)} pour \(a+i\times b\), ou bien avec la fonction \cmd{cpx.Zp(r, theta)} pour \(r\times e^{i\theta}\) en coordonnées polaires. \begin{itemize} \item Exemple : \code{local z = cpx.Z(a,b)} va créer le complexe correspondant à \(a+i\times b\) dans la variable $z$. On accède alors aux parties réelle et imaginaire de $z$ comme ceci : \code{z.re} et \code{z.im}. On peut bien sûr créer un raccourci vers cette fonction avec l'instruction \code{local Z = cpx.Z} en début de code. \item \textbf{Attention} : un nombre réel $x$ n'est pas considéré comme complexe par Lua. Cependant, les fonctions proposées pour les constructions graphiques font la vérification et la conversion réel vers complexe. On peut néanmoins, utiliser $Z(x,0)$ à la place de $x$. \item Les opérateurs habituels ont été surchargés ce qui permet l'utilisation des symboles habituels, à savoir : +, x, -, /, ainsi que le test d'égalité avec = (ce test d'égalité est fait à \varglob{ld.epsilon} près où \varglob{ld.epsilon} et une variable globale qui vaut $1e-16$ par défaut). Lorsqu'un calcul échoue le résultat renvoyé en principe doit être égal à \nil. \item À cela s'ajoutent les fonctions suivantes : \begin{itemize} \item le module : \cmd{cpx.abs(z)}, \item le module au carré: \cmd{cpx.abs2(z)}, \item la normalisation : \cmd{cpx.normalize(z)} (renvoie \emph{nil} si $z$ est nul), \item la norme 1 : \cmd{cpx.N1(z)}, \item l'argument principal : \cmd{cpx.arg(z)}, \item le conjugué : \cmd{cpx.bar(z)}, \item l'égalité parfaite : \cmd{cpx.equal(z1,z2)}, \item l'exponentielle complexe : \cmd{cpx.exp(z)}, \item le cosinus et sinus hyperboliques complexes : \cmd{cpx.cosh(z)} et \cmd{cpx.sinh(z)}, \item la fonction puissance $a$ : cmd{cpx.pow(z,a)} (le calcul utilise l'argument principal de $z$), \item le produit scalaire : \cmd{cpx.dot(z1, z2)}, où les complexes représentent des affixes de vecteurs, \item le déterminant : \cmd{cpx.det(z1, z2)}, \item l'angle orienté (en radians) entre deux vecteurs non nuls : \cmd{cpx.angle(z1, z2)} \item l'arrondi : \cmd{cpx.round(z, nb decimales)}, \item la fonction : \cmd{cpx.isNul(z)} teste si les parties réelle et imaginaire de \emph{z} sont en valeur absolue inférieures à la variable globale \varglob{ld.epsilon} qui vaut $1e-16$ par défaut, \item la fonction \cmd{cpx.isComplex(u)} teste si \argu{u} est un complexe ou non et renvoie un booléen (attention : si \argu{u} est réel, la fonction renvoie \false), \item la fonction \cmd{cpx.toComplex(x)} teste si \argu{x} est un réel, si c'est le cas, elle renvoie le nombre complexe \code{cpx.Z(x,0)}, si \argu{x} est un nombre complexe la fonction renvoie \argu{x}, et dans les autres cas, elle renvoie \nil, \item la fonction \cmd{cpx.isobar(L)} où \argu{L} est une liste de nombres complexes, renvoie l'isobarycentre des points de \argu{L}. \end{itemize} \end{itemize} On dispose également de la constante \varglob{cpx.I} qui représente l'imaginaire pur $\imath$. Exemple : \begin{Luacode} local cpx = luadraw.cpx local i = cpx.I local A = 2+3*i \end{Luacode} Le symbole de multiplication est obligatoire. \subsection{Afficher une variable dans le terminal} L'instruction \cmd{ld.whatis(variable \fac{, msg})} affiche dans le terminal lors de la compilation, le type de la \argu{variable} ainsi que son contenu. Les types reconnus sont, les types prédéfinis plus : \emph{complex number}, \emph{list of (complex) numbers}, \emph{list of lists of (complex) numbers}. L'argument \emph{msg} est une chaîne optionnelle (vide par défaut) qui est affichée avec le type pour repérer la variable dans le terminal. \subsection{Création d'un graphe} Comme cela a été vu plus haut, la création se fait dans un environnement \luadrawenv, cette création se fait en nommant le graphique : \begin{Luacode} local ld = luadraw local g = ld.graph:new{ window = {x1,x2,y1,y2 [,xscale,yscale]}, margin = {left,right,top,bottom}, size = {width,height,ratio}, bg = "color", border =true/false, bbox = true/false, pictureoptions = "" } \end{Luacode} La classe \emph{ld.graph} est définie dans le paquet \luadrawenv. On instancie cette classe en invoquant son constructeur et en donnant un nom (ici c'est \emph{g}), on le fait en local de sorte que le graphique \emph{g} ainsi créé, n'existera plus une fois sorti de l'environnement (sinon \emph{g} resterait en mémoire jusqu'à la fin du document). Voici les options du constructeur \cmd{ld.graph:new{}}: \begin{itemize} \item \opt{window=\{x1,x2,y1,y2 \fac{,xscale,yscale}\}}. Cette option (facultative) définit le pavé de $\mathbf R^2$ dans lequel se fait au graphique (c'est $[x_1;x_2]\times[y_1;y_2]$), ainsi que les échelles sur les axes, qui sont les arguments \argu{xscale} et \argu{yscale}. Ces deux derniers paramètres sont facultatifs et valent $1$ par défaut, ils représentent l'échelle (cm par unité) sur les axes. Par défaut on a \opt{window=\{-5,5,-5,5,1,1\}}. \item \opt{margin=\{left,right,top,bottom\}}. Cette option (facultative) définit des marges autour du graphique en cm. Par défaut on a \opt{margin=\{0.5,0.5,0.5,0.5\}}. \item \opt{size=\{width,height \fac{,ratio}\}}. Cette option (facultative) permet d'imposer une taille (en cm, marges incluses) pour le graphique, l'argument \argu{ratio} est facultatif et correspond au rapport d'échelle souhaité (\argu{xscale}/\argu{yscale}), un ratio de $1$ donnera un repère orthonormé, et si le ratio n'est pas précisé alors le ratio par défaut est conservé (celui défini par l'option \opt{window}). Un ratio égal à $0$ détermine les échelles de telle sorte que le graphique ait exactement la taille demandée. L'utilisation de ce paramètre va modifier les valeurs de \argu{xscale} et \argu{yscale}. Par défaut la taille est de $11\times11$ (en cm) avec les marges ($10\times10$ sans les marges). \item \opt{bg="color"}. Cette option (facultative) permet de définir une couleur de fond pour le graphique, cette couleur est une chaîne de caractères représentant une couleur pour TikZ. Par défaut cette chaîne est vide ce qui signifie que le fond ne sera pas peint. \item \opt{border=true/false}. Cette option (facultative) indique si un cadre doit être dessiné ou non autour du graphique (en incluant les marges). Par défaut ce paramètre vaut \false. \item \opt{bbox=true/false}. Cette option (facultative) indique si une boundingbox doit être ajoutée au graphique de telle sorte que celui-ci ait la taille souhaitée, tout ce qui en sort est clippé par TikZ. Par défaut ce paramètre vaut \true. Avec la valeur \false il n'y a pas de boundingbox ajoutée, mais tout ce qui sort de la fenêtre 2D, sauf les path, est clippé par \luadrawenv, la taille du graphique peut être plus petite que celle demandée. \item \opt{pictureoptions=""}. Cette option (facultative) est une chaîne de caractères destinée à contenir des options qui seront passées à l'environnement \emph{tikzpicture} comme ceci: \begin{TeXcode} \begin{tikzpicture}[line join=round <,pictureoptions>] \end{TeXcode} \end{itemize} \paragraph{Construction du graphique.} \begin{itemize} \item L'objet instancié (\emph{g} ici dans l'exemple) possède un certain nombre de méthodes permettant de faire du dessin (segments, droites, courbes,\dots). Les instructions de dessins ne sont pas directement envoyées à \TeX, elles sont enregistrées sous forme de chaînes dans une table qui est une propriété de l'objet \emph{g}. C'est la méthode \cmd{g:Show()} qui va envoyer ces instructions à \TeX\ tout en les sauvegardant dans un fichier texte\footnote{Ce fichier contiendra un environnement \emph{tikzpicture}.}. La méthode \cmd{g:Save()} enregistre le graphique dans le fichier désigné par l'option (de l'environnement) \opt{name} mais sans envoyer les instructions à \TeX. \item On peut faire une sauvegarde du graphique en cours dans un autre fichier avec la méthode: \cmdln{g:Savetofile()}. \item On peut réinitialiser un graphique en cours, c'est-à-dire supprimer tous les éléments déjà créés, avec la méthode: \cmdln{g:Cleargraph()}. \item Le paquet \luadrawenv fournit aussi un certain nombre de fonctions mathématiques, ainsi que des fonctions permettant des calculs sur les listes (tables) de complexes, des transformations géométriques, \ldots{} etc. Ces fonctions sont dans l'espace de noms \luadrawenv. \end{itemize} \paragraph{Système de coordonnées. Repérage} \begin{itemize} \item L'objet instancié (\emph{g} ici dans l'exemple) possède : \begin{enumerate} \item Une vue originelle : c'est le pavé de $\mathbf R^2$ défini par l'option \opt{window} à la création. Celui-ci \textbf{ne doit pas être modifié} par la suite. \item Une vue courante : c'est un pavé de $\mathbf R^2$ qui doit être inclus dans la vue originelle, ce qui sort de ce pavé sera clippé. Par défaut la vue courante est la vue originelle. Pour retrouver la vue courante on peut utiliser la méthode \cmd{g:Getview()} qui renvoie une table \code{\{x1,x2,y1,y2\}}, celle-ci représente le pavé $[x_1;x_2]\times [y_1;y_2]$. \item Une matrice de transformation : celle-ci est initialisée à la matrice identité. Lors d'une instruction de dessin les points sont automatiquement transformés par cette matrice avant d'être envoyés à TikZ. \item Un système de coordonnées (repère cartésien) lié à la vue courante, c'est le repère de l'utilisateur. Par défaut c'est le repère canonique de $\mathbf R^2$, mais il est possible d'en changer. Admettons que la vue courante soit le pavé $[-5;5]\times[-5;5]$, il est possible par exemple, de décider que ce pavé représente l'intervalle $[-1;12]$ pour les abscisses et l'intervalle $[0;8]$ pour les ordonnées, la méthode qui fait ce changement va modifier la matrice de transformation du graphe, de telle sorte que pour l'utilisateur tout se passe comme s'il était dans le pavé $[-1;12]\times [0,8]$. On peut retrouver les intervalles du repère de l'utilisateur avec les méthodes:\par \hfil\cmd{g:Xinf()}, \cmd{g:Xsup()}, \cmd{g:Yinf()} et \cmd{g:Ysup()}.\hfil \end{enumerate} \item On utilise les nombres complexes pour représenter les points ou les vecteurs dans le repère cartésien de l'utilisateur. \item Dans l'export TikZ les coordonnées seront différentes car le coin inférieur gauche (hors marges) aura pour coordonnées $(0,0)$, et le coin supérieur droit (hors marges) aura des coordonnées correspondant à la taille (hors marges) du graphique, et avec $1$ cm par unité sur les deux axes. Ce qui fait que normalement, TikZ ne devrait manipuler que de \og petits\fg\ nombres. \item La conversion se fait automatiquement avec la méthode \cmd{g:strCoord(x, y)} qui renvoie une chaîne de la forme \emph{(a,b)}, où \emph{a} et \emph{b} sont les coordonnées pour TikZ, ou bien avec la méthode \cmd{g:Coord(z)} qui renvoie aussi une chaîne de la forme \emph{(a,b)} représentant les coordonnées TikZ du point d'affixe $z$ dans le repère de l'utilisateur. \end{itemize} \subsection{Peut-on utiliser directement du TikZ dans l'environnement \luadrawenv ?} Supposons que l'on soit en train de créer un graphique nommé \emph{g} dans un environnement \luadrawenv. Il est possible d'écrire une instruction TikZ lors de cette création, mais pas en utilisant \code{tex.sprint("")}, car alors cette instruction ne ferait pas partie du graphique \emph{g}. Il faut pour cela utiliser la méthode \cmd{g:Writeln("")}, avec la contrainte que \textbf{les antislash doivent être doublés}, et sans oublier que les coordonnées graphiques d'un point dans \emph{g} ne sont pas les mêmes pour TikZ. Par exemple : \begin{Luacode} g:Writeln("\\draw"..g:Coord(Z(1,-1)).." node[red] {Texte};") \end{Luacode} Ou encore pour changer des styles : \begin{Luacode} g:Writeln("\\tikzset{every node/.style={fill=white}}") \end{Luacode} Dans une présentation beamer, cela peut aussi être utilisé pour insérer des pauses dans un graphique : \begin{Luacode} g:Writeln("\\pause") \end{Luacode}