Introduction | Objets fondamentaux |
Messages émis et reçus |
Interface graphique |
Scripts | Référence | Index des fonctions |
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êtesask()
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 eLN2
: le logarithme népérien de 2LN10
: le logarithme népérien de 10LOG2E
: le logarithme de base 2 eLOG10E
: le logarithme de base 10 ePI
: la constante PITWO_PI
: deux fois PITHIRD_PI
: PI divisé par 3QUARTER_PI
: PI divisé par 4HALF_PI
: Pi divisé par 2SQRT1_2
: la racine carrée d'un demiSQRT2
: la racine carrée de deux
Fonctions mathématiques :
abs(x)
: valeur absolue de xacos(x)
: arccosinus de xasin(x)
: arcsinus de xatan(x)
: arctangente de xatan2(x,y)
: arctangente de x divisé par yceil(x)
: prochain int au-dessus de xcos(x)
: cosinus de xexp(x)
: exponentielle de xfloor(x)
: rochain int en-dessous de xlog(x)
: logarithme de xmin(x,y)
:minimum de x et ymax(x,y)
: maximum de x et ypow(x,y)
: x puissance yround(x)
: x arrondisin(x)
: sinus de xsqrt(x)
: racine carrée xsq(x)
: x carrétan(x)
: tangente de xdegrees(x)
: convertit l'angle x (en radian) en degréradians(x)
: convertit l'angle x (en degré) en radianrandom(low, high)
: retourne un nombre aléatoire entre low et highconstrain(x, min, max)
: jette les valeurs de x en-dessous de min et au-dessus de maxdist(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,
avecmid
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 entrelow1
ethigh1
:
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"); }