Introduction | Objets fondamentaux | Messages émis et reçus | Interface graphique | Scripts | Référence | Index des fonctions

English version

## Principe

Avec IanniX, vous pouvez écrire vos propres scripts pour plus facilement créer des projets complexes. Les scripts sont écrits en Javascript mais même avec des connaissances limitées de Javascript, plusieurs types de scripts utiles peuvent être créés. En plus de cette documentation, plusieurs exemples de scripts sont fournis pour votre étude. Vous pouvez les trouver dans la section Scripts et Styles de l'inspecteur.

Pour regarder un script, cliquez-droit sur un script dans l'explorateur et choisissez `Open`. Le menu de contexte contient aussi d'autres pour fonctionner avec les scripts. De plus, vous pouvez exécuter un script en double-cliquant sur son nom dans l'inspecteur.

Si vous voulez en apprendre plus sur le Javascript, pour créer des scripts plus avancés, il y a de nombreux livres, tutoriels en ligne and de référence disponibles pour vous aider. Aussi, n'hésitez pas à rechercher sur le forum de IanniX pour plus d'informations sur les conventions utilisées en écriture Javascript, ou pour des astuces pour écrire des scripts pour Iannix.

Voici un lien vers la référence complète de la version de Javascript utilisée dans IanniX : Référence

## Contrôler IanniX à partir d'un script

### La commande Javascript `run()`

La fonction run() est utilisée pour envoyer la plupart de commandes à IanniX à partir d'un script. Les commandes doivent être fournies à run() en tant que chaîne unique, les commandes de textes doivent donc être entre guillemets. Exemple :

`run("zoom 100");` Définit le zoom à 100%

Pour combiner des paramètres numériques avec des commandes de texte, afin de produire une chaîne à envoyer à `run()`, utilisez l'opérateur de concaténation. Dans l'exemple suivant, center_x et center_y sont des variables numériques et doivent être concaténées en chaîne.

`run("setPos current " + center_x + " " + center_y + " 0");`

Autres exemples :

- Effacer la partition :
  `run("clear");`
- Définir le zoom à 100% :
  `run("zoom 100");`
- Donne au trigger un ID basé sur la valeur de la variable `myID` :
  `run("add trigger " + myID);`
- Définit le groupe d'un trigger à "foo" :
  `run("setGroup current foo");`
- Définit la position du trigger aux coordonnées x=1, y=3, z=0 :
  `run("setPos current 1 3 0");`
- Définit le message du trigger :
  `run("setMessage current 1, osc://127.0.0.1:57120/trigger trigger_id trigger_xPos trigger_yPos cursor_id");`
- Diminue de moitié la taille du trigger :
  `run("setSize current 0.5");`

N'oubliez pas le «`;`» à la fin de chaque ligne. Notez que les constantes numériques ou les paramètres de type chaîne peuvent être inclus directement dans la commande de texte, tandis que les valeurs dans les variables doivent être jointes avec l'opérateur de concaténation. N'oubliez pas d'inclure des espaces dans les chaînes concaténées pour que les commandes et les paramètres dans la chaîne résultante soient séparés d'au moins un espace.

Voir Index des fonctions pour obtenir la liste des fonctions que vous pouvez utiliser dans la commande `run()` pour contrôler IanniX.

### Les commandes `title()` et `ask()`

En plus de `run()`, deux autres fonctions Javascript functions sont fournies pour écrire un script :

- Déclare "name" en tant que nom de votre projet :
  `title("name");`
- Ouvre une fenêtre où l'utilisateur peut remplir les constantes pour initialiser le script :
  `ask("category, label, variable, defaultValue);`
  Le paramètre «category» permet de regrouper plusieurs requêtes `ask()` sous un nom. Toutes les requêtes de la même catégorie sont regroupées sous le nom «category». «Label» est utilisé en tant qu'affichage de la requête. «Variable» est le nom d'une variable créée pour contenir les données. «Default» est la valeur suggérée à l'utilisateur en tant que valeur par défaut de la variable. L'utilisateur est libre de nommer les catégories, labels et les variables tels que requis.

### La structure d'un script

IanniX exécute un script en plusieurs phases. Vous pouvez contrôler la phase dans laquelle vos commandes sont utilisées en les regroupant dans des fonctions appelées lors de phases spécifiques de l'exécution. Ces fonctions sont :

- Appelé par IanniX pour préparer un script à être exécuté :
  `onCreate()`
  {
  //Insérer vos commandes ici
  };
- Appelé par IanniX pour mener à bien les actions prévues par le script :
  `onConfigure()
  {
  //Insérer vos commandes ici
  };`
- Appelé à chaque fois que IanniX reçoit un message OSC. Cette section est seulement nécessaire pour les scripts qui reçoivent des messages OSC. (Par exemple pour le script de configuration) :
  `onMessage()
  {
  //Insérer vos commandes ici
  };`

Voici l'exemple d'un script simple :

              //Configuration du script
              function onConfigure() {
                  title("My new script");             //Nomme le script

                  //Demande les paramètres pour personnaliser le comportement du script
                  iannix.ask("Triggers", "Trigger x-position", "trigger_xPosition", 3);
              }

              //Création de la partition
              function onCreate() {
                  run("clear");                       //Efface les objets de la partition
                  run("center 0 0");                  //Se centre sur l'origine de la partition
                  run("zoom 100");                    //100% zoom

                  run("add trigger 1");               //Ajoute un trigger d'ID 1
                  run("setPos current 1 2 0");        //Déplace le trigger aux coordonnées (1, 2, 0)

                  addATrigger();                      //Appelle votre fonction personnalisée
              }

              //Définit une fonction personnalisée
              function addATrigger() {
                  //Insérer le code pour ajouter et configurer un trigger ici.
                  //Normalement la fonction addATrigger() doit avoir des paramètres à passer pour ajouter le trigger.
              }

Les deux seules fonctions qui doivent être dans la fonction `configure()` sont `title() et `ask()`. Le reste du code à exécuter doit être placé dans la fonction `create()`. Vous pouvez aussi définir vos propres fonctions, constantes, etc. en plus des fonctions principales. Comme par exemple, la fonction `addATrigger()`, ci-dessus.`

### Créer vos propres fonctions

Exemple : Cette fonction donne un nombre aléatoire entre les paramètres `min` et `max`.

`function randomFloat(min, max) {
return Math.random() * (max-min) + min;
}`

### Créer vos propres bibliothèques de fonctions

Iannix donne la possibilité de prédéfinir des bibliothèques de fonctions fréquemment utilisées dans les scripts. Les fichiers de type `<name>.js` dans le dossier Outils sont scannés au démarrage de IanniX et les variables, classes et fonctions sont rendues disponibles pour leur utilisation dans les scripts. Notez que si une bibliothèque de fichier est éditée lorsque IanniX est lancé, IanniX doit être redémarré pour que les modifications prennent effet.

### Variables et fonctions prédéfinies

IanniX inclut une bibliothèque de fonctions d'aide définie dans le fichier "JavaScript Library.js."
Cette bibliothèque inclut les fonctions suivantes :

### Constantes utiles :

- `E` : la constante mathématique e
- `LN2` : le logarithme népérien de 2
- `LN10` : le logarithme népérien de 10
- `LOG2E` : le logarithme de base 2 e
- `LOG10E` : le logarithme de base 10 e
- `PI` : la constante PI
- `TWO_PI` : deux fois PI
- `THIRD_PI` : PI divisé par 3
- `QUARTER_PI` : PI divisé par 4
- `HALF_PI` : Pi divisé par 2
- `SQRT1_2` : la racine carrée d'un demi
- `SQRT2` : la racine carrée de deux

### Fonctions mathématiques :

- `abs(x)` : valeur absolue de x
- `acos(x)` : arccosinus de x
- `asin(x)` : arcsinus de x
- `atan(x)` : arctangente de x
- `atan2(x,y)` : arctangente de x divisé par y
- `ceil(x)` : prochain int au-dessus de x
- `cos(x)` : cosinus de x
- `exp(x)` : exponentielle de x
- `floor(x)` : rochain int en-dessous de x
- `log(x)` : logarithme de x
- `min(x,y)` :minimum de x et y
- `max(x,y)` : maximum de x et y
- `pow(x,y)` : x puissance y
- `round(x)` : x arrondi
- `sin(x)` : sinus de x
- `sqrt(x)` : racine carrée x
- `sq(x)` : x carré
- `tan(x)` : tangente de x
- `degrees(x)` : convertit l'angle x (en radian) en degré
- `radians(x)` : convertit l'angle x (en degré) en radian
- `random(low, high)` : retourne un nombre aléatoire entre low et high
- `constrain(x, min, max)` : jette les valeurs de x en-dessous de min et au-dessus de max
- `dist(x1, y1, z1, x2, y2, z2)` : distance entre les points `(x1, y1, z1)` et `(x2, y2, z2)`

### Fonctions d'échelle des données

- Dimensionne x pour couvrir les rangs de low à high, en assumant que x est entre 0.0 et 1.0 :
  `norm(x, low, high)`:
- Dimensionne x pour couvrir les rangs de low à high, en assumant que x est entre 0.0 et 1.0,
  avec `mid` qui retourne la valeur correspondant à x=0.5:
  `rangeMid(x, low, mid, high)`
- Dimensionne x pour couvrir les rangs de `low2` à `high2`, en assumant que x est entre `low1` et `high1` :
  `map(x, low1, high1, low2, high2)`

## Tracé de courbes

IanniX offre la fonction `plot()` pour vous aider à tracer en 2D ou en 3D des courbes paramétriques basées sur des fonctions mathématiques, en utilisant soit les coordonnées cartésiennes soit polaires.

Une courbe paramétrique est définie comme la fonction d'un paramètre indépendant (souvent appelé t) qui définit les valeurs des coordonnées tracées comme une fonction de t. Pour le tracé de coordonnées cartésiennes (ex : x, y, x) vous devez fournir les fonctions qui définissent les valeurs de x, y et z (facultatif), comme une fonction de t. Pour des coordonnées polaires, vous devez fournir les fonctions de t pour définir r (le radius), theta (l'angle) et (phi) (l'angle au-dessus ou en-dessous du plan). Dans IanniX, les fonctions doivent définir les coordonnées pour des valeurs t entre 0.0 et 1.0.

Le tracé de courbes caractéristiques utilise un certain nombre de fonctionnalités avancées de Javascript, mais vous pouvez l'utiliser en insérant vos équations dans de simples patterns, un pattern pour un tracé de courbe en x, y, z (Cartésien) et un autre pour un tracé de courbe en coordonnées polaires.

### Tracé de courbes en coordonnées cartésiennes

Remplacez le texte à droite des deux points des variables x, y et z par vos expressions. N'oubliez pas d'inclure la virgule à la fin de l'expression.

              plot(function(t){ return {
                 index   : 0, nbPoints: 300,
                 offset  : {x: 0, y:0, z:0},

                 x   : expression donnant x en fonction de t,
                 y   : expression donnant y en fonction de t,
                 z   : expression donnant z en fonction de t,

                 t   : [0,1]
              }});

### Tracé de courbes en coordonnées polaires

Remplacez le texte à droite des deux points des variables theta, r et phi par vos expressions. N'oubliez pas d'inclure la virgule à la fin de l'expression.

              plot(function(t) { return {
                 index   : 0, nbPoints: 300,
                 offset  : {x: 0, y:0, z:0},

                 theta   : expression donnant l'angle theta (en radians) en fonction de t,
                 r       : expression donnant r en fonction de t,
                 phi     : expression donnant l'angle phi (en radians) en fonction de t,

                 t       : [0,1]
              }});

### Exemple : script pour créer une courbe parabolique en utilisant les coordonnées polaires

Pour voir le résultat de ce script, lancez l'exemple "Simple Parabola" dans les fichiers exemples de l'inspecteur.

              function onCreate() {
                  //Configuration de l'affichage
                  run("clear");
                  run("center 0 0");
                  run("rotate 0 0 0");
                  run("zoom 100");

                  run("add curve  1000");
                  run("setPos     current 0 0 0");

                  //Tracé de la courbe
                  plot(function(t) { return {
                      index   : 0, nbPoints: 300,
                      offset  : {x: 0, y:0, z:0},

                      x   : 5*t,   //ex : x = 5 fois t
                                   //(comme t va de 0 à 1, x va de 0 à 5.)

                      y   : 3*t*t, //ex : y = 3 fois t au carré
                                   //(comme t va de 0 à 1, y va de 0 à 3.)

                      z   : 0,     //z est toujours égal à 0

                      t       : [0,1] }});

                  //Rajouter un curseur
                  run("add cursor 1001");
                  run("setCurve   current lastCurve");
                  run("setSpeed   current auto 100");
              }

### Exemple : script pour créer une spirale simple en utilisant les coordonnées polaires

Pour voir le résultat de ce script, lancez l'exemple "Simple Spiral" dans les fichiers exemples de l'inspecteur.

              function onCreate() {
                  //Configuration de l'affichage
                  run("clear");
                  run("center 0 0");
                  run("rotate 0 0 0");
                  run("zoom 100");

                  run("add curve  1000");
                  run("setPos     current 0 0 0");

                  //Tracé de courbe
                  plot(function(t) { return {
                      index   : 0, nbPoints: 300,
                      offset  : {x: 0, y:0, z:0},

                      theta   : TWO_PI * t,	  //ex : theta = deux Pi fois t
                            //(comme t va de 0 à 1, theta va de 0 à deux Pi.)
                            //Comme un angle de 2*Pi en radians correspond à 360 degrés, theta
                            //effectue une rotation une fois pendant que t va de 0 à 1.

                      r       : 3*t,          //ex : x = 3 fois t
                            //(Comme t va de 0 à 1, le radius va de 0 à 3.)

                      phi     : 0,		  //phi est toujours égal à 0

                      t       : [0,1] }});

                  //Rajouter un curseur
                  run("add cursor 1001");
                  run("setCurve   current lastCurve");
                  run("setSpeed   current auto 100");
              }

Pour un exemple des courbes intéressantes et complexes que vous pouvez facilement créer avec des équations paramétriques, essayez de dupliquez (avec le menu de contexte) l'exemple "Learn - Simple Spiral" dans les scripts exemples de l'inspecteur de IanniX. Ouvrez ensuite le script avec le menu de contexte et changez `phi : 0` en `phi : sin(20*t)`. Exécutez le script en double-cliquant dessus dans l'inspecteur. Maintenez ensuite le touche Alt et faîtes glisser la souris sur la partition pour voir la courbe sinusoïdale que vous venez de créer. Lancez la lecture du curseur pour le voir onduler sur la courbe.

## Dessiner des courbes de Bézier

La fonction setPointAt() de IanniX permet aux scripts de créer des courbes en 2D et en 3D à partir d'une séquence de lignes droites et de segments courbés (Bézier cubique).

### Créer une courbe

Commencez une nouvelle courbe avec :
`run("add curve id");`
Créer un objet courbe avec l'ID spécifié. La courbe n'a encore reçu aucun points. La localisation d'un nouvel objet est par défaut (0,0,0).

### La fonction setPointAt

La fonction setPointAt est utilisée pour ajouter des points ou changer des points sur une courbe. Le comportement de la fonction setPointAt() diffère selon les paramètres reçus :

- Pour définir le premier point de la trajectoire :
  `run("setPointAt id 0 x y <z>");
  définit le point 0 à x, y (et facultativement z pour une trajectoire 3D).`
- Pour ajouter un segment de ligne droite à la trajectoire :
  `run("setPointAt id pNum x y <z>");`
  où pNum est le nombre du point précédant toujours le point de nombre pNum+1.
- Pour changer le point final d'un segment de ligne droite d'une trajectoire existante :
  `run("setPointAt id pNum x y <z>");`
  où pNum est le nombre du point à changer.
- Pour ajouter un segment courbé et définir sa courbure :
  `run("setPointAt id pNum x y <z> dxStart dyStart <dzStart> dxEnd dyEnd <dzEnd> ");`
  où le point final du segment est x, y et facultativement z. Le segment démarre tangent à une ligne depuis son point de départ, (la fin du segment précédent) jusqu'au point `(xStart+dxStart, yStart+dyStart, <zStart+dZstart>)`. Le segment finit tangent à une ligne de son point final `(x, y, <z>)` au point `(x+dxEnd, y+dyEnd, <z+dyEnd>)`. Notez que le point de départ sera le point `(x, y, <z>)` dans l'appel précédent de setPointAt.
- Pour changer un segment courbé précédemment défini :
  `run("setPointAt id pNum cx1 cy1 <cz1> cx2 cy2 <cz2> x y <z>");`
  où pNum est le nombre d'un point précédemment définir et les autres paramètres comme définis ci-dessus.

  (Les paramètres optionnels sont indiqués entre parenthèses < >)

Tous les champs de `setPointAt` spécifient la localisation du point comme x y <z>. Les paramètres qui spécifient les segments de Bézier incluent deux autres points, cx1 cy1 <cz1> et cx2 cy2 <cz2>, qui décrivent la courbure. La direction de la courbe quittant son point de départ est tangente à la ligne à partir du point de départ jusqu'au premier point de contrôle cx1 cy1 <cz1>. La direction de la courbe arrivant à son point final est tangente à la ligne à partir du point de contrôle cx2 cy2 <cz2> jusqu'au point final x y <z>.

### Exemple d'une création de courbe avec des segments 2D et 3D

Le code suivant est celui de l'exemple "Learn - Curve points" qui peut être trouvé dans l'explorateur de scripts de l'inspecteur. Il créé une trajectoire avec cinq segments et cinq points. Le premier segment est une ligne droite en 2D, la seconde est une courbe de Bézier 2D, la suivante est une ligne droite en 3D et le quatrième segment est une Bézier 3D. Lancez le script d'exemple pour voir à quoi ressemble la courbe. Pour voir sa forme en 3D, pressez la touche Alt et glissez la souris sur la partition. Vous pouvez réinitialiser l'angle de vue en lançant le script "Reset orientation" dans la section Outils du navigateur de scripts.

              //Création de la partition
              function onCreate() {
                  //Configuration de la vue
                  run("clear");
                  run("center 0 0");
                  run("zoom 100");
                  run("rotate 0 0 0");

                  //Création de la courbe
                  run("add curve  1000");

                  //Point numéro 0
                  //Coordonnées x0 = -2, y0 = 1
                  run("setPointAt current  0  -2 1");

                  //Dessine un segment droit en 2D du point numéro 0 au
                  //point numéro 1, qui est à (x1,y1) = (-2,3)
                  run("setPointAt current  1   -2  3");

                  //Dessine un segment de Bézier en 2D du point numéro 1 au
                  //point numéro 2, qui est à (x2,y2) = (2,3)
                  //Le segment de départ est tangent à la ligne de (x1,y1) à (x1+2, y1+2)
                  //Le segment de fin est tangent à la ligne de (x2,y2) à (x2+0,x2+3)
                  run("setPointAt current  2    2  3   +2 +2   +0 +3 ");

                  //Dessine un segment droit en 3D du point numéro 2 au
                  //point numéro 3, qui est à (x3,y3,z3) = (0,2,1)
                  run("setPointAt current  3    0 2 1");

                  //Dessine un segment de Bézier en 3D du point numéro 3 au
                  //point numéro 4, qui est à (x4,y4,z4) = (-2,-1,0)
                  //Il commence tangent à la ligne de (x3,y3,z3) à (x3+0,y3-1,z3+2)
                  //Finit tangent à la ligne de (x4,y4,z4) à (x4+4,x4+0,z4+0)
                  run("setPointAt current  4   -2 -1 0   +0 -1 +2   +4 +0 +0");

                  //Rajoute un curseur sur la courbe
                  run("add cursor 1");
                  run("setCurve   current lastCurve");
                  run("setSpeed   current auto 10");
              }