Page suivante Page précédente Table des matières

6. Interface de script

L'interface de script Ayam se compose d'un certain nombre de procédures Tcl et de commandes Tcl qui sont également utilisées en interne par l'application. L'entrée du menu principal "File/New" par exemple appelle la commande de l'interface de script "newScene" (parmi d'autres commandes). Utiliser l'interface de script signifie appeler ces commandes par vous-même, éventuellement en les mélangeant avec du code de script Tcl standard.

De plus, en utilisant Tcl et ses capacités d'introspection, vous pourriez facilement modifier le code dont est composé Ayam. Cela n'est cependant pas recommandé pour de bonnes raisons (à moins que vous ne lisiez le code source de Ayam et que vous sachiez vraiment ce que vous faites). Faites donc attention aux procédures et commandes déjà existantes lorsque vous implémentez les vôtres. L'utilisation de procédures et de commandes non mentionnées dans cette documentation est également dangereuse. L'implémentation et les interfaces de ces procédures et commandes peuvent changer dans les futures versions de Ayam sans préavis.

Dans Tcl, toutes les variables, procédures et commandes sont sensibles à la casse, ce qui fait que "sL" est différent de "sl", de "Sl"et de "SL".

L'interface de script peut être utilisée directement depuis la console de Ayam. Vous pouvez, bien sûr, également écrire des scripts dans vos propres fichiers de script Tcl, qui peuvent être chargés à tout moment dans Ayam en utilisant la console et la commande Tcl "source". Vous pouvez également faire en sorte qu'un fichier script soit exécuté automatiquement à chaque démarrage de l'application en utilisant le paramètre de préférence "Main/Scripts". De plus, sur les systèmes X11 et Aqua window, Ayam est capable d'exécuter du code script envoyé via la commande Tk "send" ou la commande AppleScript "tell" à partir d'applications externes.

Contrairement à d'autres environnements de modélisation, dans Ayam, il existe encore une autre façon d'exécuter des scripts. Dans Ayam, les scripts peuvent également être attachés à des objets Script et s'exécuter lorsque le mécanisme de notification met à jour la scène. Voir aussi la section L'objet Script.

Même les objets normaux peuvent déclencher des scripts sur notification en utilisant les balises BNS ou ANS. Voir aussi la sections Balise BNS (Before Notify Script) et Balise ANS (After Notify Script).

Notez que la plupart des commandes de l'interface de script énumérées dans cette documentation fonctionnent en arrière-plan, sans rien changer à l'interface graphique Ayam et aux fenêtres de visualisation Ayam, pour des raisons de rapidité d'exécution. Si vous souhaitez que vos modifications soient visibles, vous devez mettre à jour les différentes parties de l'interface graphique (propriétés des interfaces graphiques, fenêtres de visualisation) de manière explicite (Voir aussi la section Mettre à jour l'interface graphique).

Cependant, depuis Ayam 1.13, il est également possible d'exécuter automatiquement des commandes de mise à jour de l'interface graphique dans la console en utilisant <Shift+Return> au lieu de <Return> lors de l'émission de commandes de l'interface de script. Notez cependant que même si aucune mise à jour de l'interface graphique n'a lieu, tous les processus de notification sont exécutés immédiatement. La scène sera cohérente et mise à jour lorsque la commande de l'interface de script sera renvoyée.

Si vous souhaitez que vos modifications soient enregistrées dans la mémoire tampon d'annulation, vous devez également le faire manuellement (voir la documentation de la commande d'annulation : Annuler).

À partir de scripts, il peut être nécessaire de vérifier si une erreur s'est produite lors de l'exécution d'une commande. Toutes les commandes renvoient TCL_OK dans tous les cas, donc la vérification de leur valeur de retour n'aboutit à rien, mais elles fixent la variable globale Tcl "ay_error" à une valeur supérieure à 1 si une erreur s'est produite. Vous devez mettre "ay_error" à zéro avant et vérifier sa valeur après l'opération en question pour voir si l'opération s'est bien déroulée :

proc myProc { } {
  set ::ay_error 0
  copOb
  if { $::ay_error > 1 } {
    ayError 2 "myProc" "Error copying object!"
  }
}

6.1 Variables et tableaux globaux

Plusieurs variables et tableaux globaux existent dans le contexte Tcl de Ayam, et qui peuvent être utiles pour les scripts.

Variables globales

La variable globale "ay_error" contient l'état d'erreur actuel. Voir aussi la section Signalement d'erreur.

La variable globale "i" est utilisée par toutes les variantes de la commande "forAll". Voir aussi la section Appliquer des commandes à un certain nombre d'objets.

Les variables globales "u" et "v" sont définies par les actions find u/uv. Voir aussi la sections Trouver des points sur les courbes and Trouver des points sur les surfaces.

Le tableau global "ay"

Le tableau global "ay" contient les variables d'état de l'application. En outre, vous pouvez trouver dans ce tableau les chemins d'accès aux widgets importants (par exemple le widget d'arbre pour la hiérarchie d'objets ou la vue actuellement active). Utilisez "parray ay" dans la console pour voir ce qui s'y trouve. Plus de documentation à venir.

Le tableau global "ayprefs"

Le tableau global "ayprefs" contient des données sur les préférences. Le tableau complet est enregistré dans le fichier ayamrc à la sortie, donc soyez prudent lorsque vous ajoutez de nouveaux éléments à ce tableau. Voir aussi la section Le fichier Ayamrc.

Utilisez "parray ayprefs" dans la console pour voir ce qui s'y trouve. Plus de documentation à venir.

Notez que les modifications apportées à ce tableau du côté Tcl ne prennent pas effet immédiatement car les données doivent être transférées dans le contexte C à l'aide de la commande "setPrefs". Voir aussi la section Gestion des préférences.

Le tableau global "aymark"

Le tableau global "aymark" contient une copie de la position actuelle de la marque. [∗] Il est mis à jour chaque fois que la marque est définie, par exemple en utilisant l'action "set mark" (voir la section Définir une marque).

Les modifications manuelles apportées à ce tableau n'ont aucun effet sur la marque.

Gestion des propriétés et tableaux de données

Pour chaque type d'objet, il existe une variable globale correspondante, qui contient les noms des propriétés de ce type d'objet sous forme de liste. Le nom de la variable est simplement le nom du type d'objet suivi de _props (pour les propriétés). Par exemple, pour le type d'objet NCurve, cette variable est nommée "NCurve_props" et la liste qu'elle contient ressemble à ceci : 

{ Transformations Attributes Tags NCurveAttr }

Cette liste est consultée chaque fois qu'un seul objet est sélectionné dans l'arborescence ou dans l'objet liste des widget et son contenu est utilisé pour remplir les propriétés de la listbox du widget. (????) Voir aussi la section Propriétés.

Notez que la liste peut être manipulée ultérieurement par les balises "NP" et "RP" de l'objet sélectionné.

Pour chaque propriété, il existe un tableau global correspondant, où la propriété est gérée. Pour la propriété Transformations, ce tableau ressemble à ceci : 

Transformations {
  arr   transfPropData
  sproc setTrafo
  gproc getTrafo
  w     fTrafoAttr
}
La première entrée, "arr", désigne le nom du tableau global de données de propriété (ainsi, les données de transformation sont stockées dans un tableau appelé "transfPropData"). Ce tableau ne contient des données utiles que lorsqu'il a été rempli explicitement par le retour de la procédure "get-property" si bien nommée.

Les entrées "sproc" et "gproc" désignent les procédures ou commandes de rappel "set-property" et "get-property". Elles sont appelées, respectivement, lorsque le bouton "Apply" est utilisé ou que la propriété est sélectionnée dans la liste des propriétés. Si "sproc" ou "gproc" sont des chaînes vides (""), les retours standards nommés "setProp" ou "getProp" seront utilisés pour obtenir ou définir les valeurs des propriétés. Mais pour la propriété Transformations, les commandes "setTrafo" et "getTrafo" doivent être utilisées. La flexibilité acquise par les procédures individuelles de "sproc"/"gproc" est utilisée pour nettoyer les entrées de l'utilisateur, exécuter un code de mise à jour supplémentaire de l'interface graphique ou réaliser des interfaces graphiques de propriétés dynamiques.

La dernière entrée, "w", est le nom de la fenêtre principale de l'interface graphique des propriétés. Pour obtenir le chemin complet et utilisable du widget de cette fenêtre, la valeur actuelle de l'entrée du tableau "ay(pca)" doit être préfixée : $ay(pca).$Transformations(w).

Notez que pour de nombreux types d'objets, la variable propriété et les tableaux de gestion de propriété spécifiques au type d'objet n'existent qu'après une procédure d'initialisation spécifique au type d'objet, dérivée du nom du type, appelée, par exemple, "init_Box". Ces type sont : "ACurve", "Bevel", "Birail1", "Birail2", "Box", "BPatch", "Cap", "ConcatNC", "ConcatNP", "Cone", "Cylinder", "Disk", "ExtrNC", "ExtrNP", "Hyperboloid", "ICurve", "IPatch", "NCircle", "OffsetNC", "OffsetNP", "PatchMesh", "Paraboloid", "Revolve", "RiInc", "RiProc", "Script", "SDMesh", "Select", "Sphere", "Sweep", "Swing", "Torus", et "Trim".

Depuis Ayam 1.16, le tableau global de gestion des propriétés peut être créé facilement en utilisant la nouvelle commande de l'interface de script "addPropertyGUI". Voir aussi la section Gestion de l'interface graphique des propriétés.

Les tableaux globaux suivants et les retours pour obtenir ou définir les données existent :

propertyarrayget-property callbackset-property callback
TransformationstransfPropDatagetTrafosetTrafo
AttributesattrPropDatagetAttrsetAttrp
MaterialmatPropDatagetMatsetMat
TagstagsPropDatagetTagspsetTagsp
MaterialAttrMaterialAttrData""setMaterialAttrp
Surfaceay_shadershader_getSurfshader_setSurf
Displacementay_shadershader_getDispshader_setDisp
Interioray_shadershader_getIntshader_setInt
Exterioray_shadershader_getExtshader_setExt
Lightay_shaderlight_getShaderlight_setShader
LightAttrLightAttrDatalight_getAttr""
ViewAttribViewAttribData""setViewAttr
CameraCameraData""setCameraAttr
NCurveAttrNCurveAttrData""""
NPatchAttrNPatchAttrData""""
ICurveAttrICurveAttrData""""
NCircleAttrNCircleAttrData""""

Tableaux de propriété et retours

Notez que cette liste est assez incomplète, mais les informations peuvent toujours être facilement déduites en utilisant la commande "parray" dans la console Ayam :

» parray NCurveAttr
Voir aussi la section Manipuler les propriétés pour plus d'informations sur la façon de modifier les valeurs des propriétés à partir de l'interface de script.

6.2 Procédures and Commandes

Cette section fournit une documentation sur les procédures et les commandes les plus importantes de l'interface de scripting de Ayam, classées par catégorie.

Notez que la commande "help" dans la console Ayam peut être utilisée pour passer directement à la sous-section appropriée de cette partie de la documentation.

Toutes les procédures et commandes sont documentées selon le schéma suivant :

Obtenir de l'aide sur les commandes de l'interface de script

Depuis Ayam 1.8.2, une commande d'interface de script appelée "help" est disponible, qui affiche l'aide des commandes d'interface de script utilisant un navigateur web (similaire à la fonction "Help on Object") :

Gérer les objets

Pour créer de nouveaux objets, la commande "crtOb" peut être utilisée.


Il existe des commandes d'aide, qui créent certaines courbes souvent utilisées :

crtNCircle – créé un cercle NURBS:


crtClosedBS – créer une B-Spline fermée (circulaire) :


crtNRect – créer une courbe NURBS rectangulaire :


crtTrimRect – créer une courbe de coupe rectangulaire de délimitation :


delOb – supprime un(des) object(s):

Interroger les objets

Ces commandes permettent d'interroger les objets sur différents aspects.

getType:


getName:


hasChild:


hasMat – a un material :


hasRefs – a une reference :


candelOb – peut être supprimé :


hasTrafo – a une transformation :


isCurve:


isSurface:


getBB – obtenir la boîte de délimitation :


getPlaneNormal – obtenir le plan normal d'un objet :


isClosed:


isPlanar – vérifier la planéité :


isDegen – vérifier la dégénérescence :


isParent:


isTrimmed:

Sélectionner des Objets

Ces commandes sont probablement les plus importantes, car de nombreuses autres commandes de l'interface de script ne fonctionnent que sur des objets sélectionnés :

selOb – selectionner un(des) objet(s):


sL – sélectionne le(s) dernier(s) objet(s) :


hSL – cache la sélection des derniers objets :

Sélection des points

Cette commande permet de manipuler la sélection des points.

selPnts – sélection des points :

Manipuler les propriétés

Ces procédures permettent d'accéder facilement aux propriétés des objets à partir de l'interface de script :[∗]

getProperty – récupére la valeur d'une propriété unique


setProperty – fixer la valeur d'une propriété unique

Opérations avec le presse-papiers

Ces commandes font fonctionner le presse-papiers d'objet :

copOb – copie le(s) objet(s) :


cutOb – cCoupe le(s) objet(s):


pasOb – Colle le(s) objet(s) :


repOb – remplace le contenu du presse-papiers par le(s) objet(s) sélectionné(s) :


clearClip – vide le presse papier des objets :


Les procédures suivantes font fonctionner le presse-papiers des propriétés, qui est totalement indépendant du presse-papiers des objets.

copyProp – copie une propriété dans le presse-papiers des propriétés.


pasteProp – Colle une propriété.

Opérations sur la hiérarchie

Ces commandes manipulent le niveau actuel de Ayam :

goDown:


goUp:


goTop:


Les commandes suivantes permettent de déplacer des objets dans la hiérarchie :

upOb – déplacer le(s) objet(s) vers l'arrière dans le niveau actuel :


downOb – déplacer le(s) objet(s) vers l'avant dans le niveau actuel :

Transformations

Ces commandes transforment des objets ou des points sélectionnés d'objets :

movOb – déplace des objets:


rotOb – tourne les objets:


scalOb – zoome les objets:


movPnts – déplace les points sélectionnés :


rotPnts – tourne les points sélectionnés :


scalPnts – zoome les points sélectionnés :


delegTrafo – délègue les transformations :


applyTrafo – applique les transformations :


normTrafos – normalise les valeurs de transformation :


normPnts – normalise les points :


normVar – normalise la variable :

Manipuler les ombrages (shaders)

Ces commandes font fonctionner les propriétés de l'ombre :

shaderSet:


shaderGet:

Manipuler les balises (tag)

Ces commandes peuvent être utilisées pour modifier les balises d'un objet (Voir aussi la section Tags).

Lors du traitement de balises de type inconnu ou non enregistré, un message d'avertissement correspondant peut être émis. Cet avertissement peut être désactivé en utilisant le paramètre de préférence cachée "WarnUnknownTag" ou en enregistrant le type de balise à l'aide de la commande "registerTag" (voir ci-dessous).

setTag:


addTag:


hasTag:


delTags:


getTags: setTags:


getTag:


registerTag:

Manipuler les courbes (Curves)

Ces commandes fonctionnent sur des courbes paramétriques :

openC – ouvre une courbe :


closeC – ferme une courbe :


refineC – affine une courbe :


coarsenC – émousse une courbe : (????)


revertC – renverser une courbe :


shiftC – décale les points de contrôle d'une courbe (fermée) :


toXYC – tourne une courbe dans le plan XY


concatC – concaténer des courbes :

Manipuler les surfaces

Ces commandes opèrent sur des surfaces paramétriques :

revertuS – retourne les surfaces sur U :


revertvS – retourne les surfaces sur V :


swapuvS – échanger les dimensions des surfaces:


concatS – concatène les surfaces:

Manipuler les courbes NURBS

Il s'agit de commandes plus spécialisées permettant de modifier les propriétés des courbes NURBS :

clampNC – resserrer la courbe NURBS :


unclampNC – desserrer une courbe NURBS :


extendNC – étendre une courbe NURBS :


elevateNC – augmente l'ordre d'une courbe NURBS :


reduceNC – diminue l'ordre d'une courbe NURBS :


insknNC – insérer des noeuds dans une courbe NURBS :


remknNC – supprime des noeuds d'une courbe NURBS :


remsuknNC – supprime les noeuds supperflus d'une courbe NURBS :


refineknNC – Affiner le vecteur noeud d'une courbe NURBS :


tweenNC – interpoler des courbes :


rescaleknNC – repositionner les noeuds d'une courbe NURBS :


splitNC – couper une courbe NURBS :


extrNC – extraire une courbe NURBS :


trimNC – ajuste une courbe NURBS :


estlenNC – estimer la longueur d'une courbe NURBS :


reparamNC – reparamétriser une courbe NURBS :


isCompNC:


makeCompNC – rendre les courbes NURBS compatibles :


interpNC – interpoler des courbes NURBS :


approxNC – approximer une courbe NURBS :


curvatNC – calculer la courbure :


fairNC – Améliorer la forme de la courbe :

Manipuler des surfaces NURBS

Il s'agit de commandes plus spécialisées pour modifier les propriétés des surfaces NURBS :

clampuNP – resserer un patch NURBS dans la direction U :


clampvNP – resserer un patch NURBS dans la direction V :


unclampuNP – desserer un patch NURBS dans la direction U :


unclampvNP – desserer un patch NURBS dans la direction V :


rescaleknNP – répartir les noeuds d'un patch NURBS :


insknuNP – insère des noeuds dans un patch NURBS :


insknvNP – insére des noueuds dans un patch NURBS :


remknuNP – enlever des noeuds u d'une surface NURBS :


remknvNP – enlever des noeuds v d'une surface NURBS :


remsuknuNP – enlève les noeuds superflus d'une surface NURBS :


remsuknvNP – enlève les noeuds superflus d'une surface NURBS :


refineuNP – affiner la surface des NURBS dans la direction du U :


refinevNP – affiner la surface des NURBS dans la direction V :


elevateuNP – élever la surface des NURBS dans la direction du U :


elevatevNP – élever la surface des NURBS dans la direction V :


reduceuNP – diminuer l'ordre d'une courbe NURBS dans la direction U :


reducevNP – diminuer l'ordre d'une courbe NURBS dans la direction V :


splituNP – divise un patch NURBS dans la direction U :


splitvNP – divise un patch NURBS dans la direction V :


extrNP – extraire un patch NURBS :


tweenNP – interpoler (tween) des surfaces:


interpuNP – interpoler la surface des NURBS dans la direction U :


interpvNP – interpoler la surface des NURBS dans la direction V :


breakNP – décomposer le patch NURBS en courbes :


buildNP – construire un patch NURBS à partir de courbes :


isCompNP:


makeCompNP – rendre les surfaces NURBS compatibles :


curvatNP – calculer la courbure gaussienne :


tobasisPM – convertir un PatchMesh sur une autre base :


tobasisBC – convertir les objets BCurve sur une base différente :

Manipuler les objets PolyMesh

Il s'agit de commandes plus spécialisées pour modifier les propriétés des objets PolyMesh :

genfnPo – générer des normales à la face :


gensnPo – générer des normales régulières :


remsnPo – supprimer des normales régulières :


flipPo – retourner les normales ou les boucles :

Manipuler des points

Utilisez ces deux commandes pour lire ou manipuler les points de contrôle des objets qui supportent l'édition de points.

getPnt – obtenir un ou des points :


setPnt – Définir un ou des points :

Mettre à jour l'interface graphique

Ces procédures mettent à jour diverses parties de l'interface utilisateur de Ayam :

rV – redessiner toutes les vues :


uS – mettre à jour ce qui est sélectionné :


uCL – mettre à jour le niveau actuel :


uCR – mettre à jour le niveau actuel après une création :


plb_update – mise à jour de la liste des propriétés :

Depuis Ayam 1.13, il est également possible d'exécuter automatiquement des commandes de mise à jour de l'interface graphique dans la console en utilisant <Shift+Return> au lieu de <Return>. Les commandes du réglage des préférences cachées "AUCommands" seront exécutées après les commandes de la ligne de commande, si la touche <Shift> est maintenue enfoncée. <Shift+Retour> peut également être utilisé sans commandes sur la ligne de commande. Par défaut, les "AUCommands" sont "uS; rV;", ce qui permet de mettre à jour l'arbre d'objets, l'interface graphique des propriétés et les vues.

Gestion des préférences

Ces commandes gèrent les données des préférences :

getPrefs – obtenir des données sur les préférences :


setPrefs – Définir les données des préférences :

Voir aussi la section Les préférences

Objets personnalisés / Plugins

Cette commande gère les objets personnalisés (plugins) :

loadPlugin – charger un objet personnalisé / plugin :

Appliquer des commandes à un certain nombre d'objets

Ces procédures et commandes permettent d'appliquer des commandes quelconques à un certain nombre d'objets sélectionnés.

forAll:


withOb – exécuter une commande sur certains des objet(s) sélectionné(s) :

Entrée/sortie de scène

Ces commandes permettent de charger des scènes et de les enregistrer dans des fichiers de scènes Ayam :

replaceScene:


insertScene:


saveScene:


newScene:

Exportation RIB

Cette commande permet d'exporter la scène en cours vers un fichier RIB (RenderMan Interface Bytestream):

wrib – exportation RIB :

Signalement d'erreur

Cette commande sert à signaler les erreurs des scripts :

ayError:

Gestion de l'interface graphique des propriétés

Ces procédures aident à gérer les GUI de propriété. Voir aussi la section Gestion des propriétés et tableaux de données.

addPropertyGUI:


Les procédures suivantes permettent d'ajouter des éléments d'interface utilisateur aux GUI de propriété créés par "addPropertyGUI".

addParam:


addString:


addCheck:


addColor:


addMatrix:


addMenu:


addFile:


addCommand:


addText:


addInfo:


addProgress:


addVSpace:


addOptionToggle:

Divers

Commandes diverses :

convOb:


Annuler :


runTool:


notifyOb:


nameOb:


setMark:


getMark:


tmpGet:


whatis:


addToProc:

6.3 Prise en charge des expressions dans les entrées de dialogue

Diverses entrées de dialogue pour la création d'objets et les outils de modélisation prennent en charge les variables et expressions Tcl. Il est par exemple possible d'entrer : 

$::u
au lieu d'une valeur numérique de noeud dans le dialogue de paramétrage de l'outil d'insertion de noeud pour déduire la valeur paramétrique de la variable globale u (qui peut avoir été définie avant d'utiliser l'action de modélisation find u) et insérer un noeud au point choisi. Il est également possible de saisir des expressions mathématiques complexes : 
[expr sin(45)]
ou faire appel à ses propres procédures (qui doivent renvoyer des valeurs correctement typées) : 
[myproc]
où "myproc" est défini ailleurs (par exemple dans un fichier de script Tcl chargé via le paramètre de préférence "Scripts") comme suit : 
proc myproc { } {
  return [expr sin(45)];
}
L'appel répété de l'outil sans ouvrir le dialogue (en utilisant le raccourci clavier <Ctrl+T>), exécutera à nouveau l'expression fournie. Cela signifie qu'un certain nombre de courbes de longueur croissante peuvent être créées en entrant dans la console Ayam : 
set ::myvar 1
puis en entrant la longueur dans le dialogue de création de la courbe NURBS : 
[incr ::myvar]
puis en appuyant plusieurs fois sur <Ctrl+T>.

6.4 Exemples de script

Voici quelques exemples complets de scripts pour l'interface de script Tcl de Ayam.

Tous les exemples peuvent être copiés à partir de la documentation et collés directement dans la console de Ayam.

Déplacer des objets

L'exemple de script suivant montre comment déplacer un objet sélectionné vers une position spécifiée dans l'espace. 

proc placeOb { x y z } {
  global transfPropData
  # copy Transformations-property data to
  # global array "transfPropData"
  getTrafo
  # set array values according to procedure parameters
  set transfPropData(Translate_X) $x
  set transfPropData(Translate_Y) $y
  set transfPropData(Translate_Z) $z
  # copy Transformations-property data from
  # global array "transfPropData" to selected object
  setTrafo
}
# placeOb
Afin de déplacer tous les objets sélectionnés vers 1 1 1, vous pouvez entrer ce qui suit dans la console : 
forAll -recursive 0 {placeOb 1 1 1}
Mais peut-être préférez-vous une petite interface graphique pour cela ? Pas de problème, l'extrait suivant ajoute une entrée au menu personnalisé qui ouvre une petite boite de dialogue pour les valeurs x-, y- et z et appelle la procédure "placeOb" (définie ci-dessus) avec elles : 
global ay
$ay(cm) add command -label "Place Object(s)" -command {
 runTool {x y z} {"X:" "Y:" "Z:"} {forAll -recursive 0 {placeOb %0 %1 %2};
   plb_update; rV
 } "Place Object(s)"
}
La commande suivante "plb_update ; rV" garantit que l'interface graphique est correctement mise à jour et que toutes les vues affichent la nouvelle position des objets

Déplacer des points NURBS

L'exemple de scénario suivant montre comment déplacer les points de contrôle d'une courbe NURBS.

# first, we create a new NURBS curve with 30 control points
set len 30
crtOb NCurve -length $len
# update selection
uS
# select last object (the newly created curve)
sL
# prepare moving
set i 0
set r 3.0
set angle 0
set angled [expr 3.14159265/2.0]
while { $i < $len } {
    set x [expr $r*cos($angle)]
    set y [expr $r*sin($angle)]
    set z [expr $i/3.0]
    # move control point to new position
    setPnt $i $x $y $z 1.0
    set angle [expr $angle + $angled]
    incr i
}
# redraw all views
rV
Maintenant, utilisez le comme chemin pour un balayage. Par exemple, en utilisant le petit script suivant.

Interpolation facile

L'exemple de script suivant montre comment créer facilement un balayage à partir d'une courbe de chemin sélectionnée (en évitant la création et le paramétrage long et manuel d'une section transversale appropriée). 

proc easySweep { } {
 # first, we create a sweep object
 crtOb Sweep
 # now, we need to move the selected curve (path) to
 # the sweep and create a cross-section curve there too
 # for that, we move the currently selected curve to the clipboard
 cutOb
 # enter the Sweep (the last object in the current level)
 goDown -1
 # now, we create a new curve (a closed B-Spline suitable as cross section)
 crtClosedBS -s 8
 # select the new object
 selOb 0
 # now, we rotate and scale the curve
 rotOb 0 90 0
 scalOb 0.25 0.25 1.0
 # move trajectory back (we use "-move", because we
 # really want to move (and not copy) the curve object
 pasOb -move
 # go up to where we came from
 goUp
 # finally, update the GUI...
 uS
 sL
 # ...and redraw all views
 rV
}
# easySweep

Exécutez cette procédure en sélectionnant un objet courbe NURBS, puis tapez dans la console :

» easySweep
Cette commande peut également être ajoutée au menu principal : 
global ay
$ay(cm) add command -label "Easy Sweep" -command {
 easySweep
}
Après l'exécution du script ci-dessus, il devrait maintenant y avoir une nouvelle entrée de menu "Custom/Easy Sweep" qui appelle la procédure easySweep.

Boutons et boite à outils

Voici un autre exemple de script qui montre comment les boutons peuvent être ajoutés à la boîte à outils. myImage doit être une image créée par exemple à partir d'un fichier GIF de taille 25 par 25 pixels. 

global ay ayprefs
# create an image from a GIF file:
image create photo myImage -format gif -file /home/user/giffile
set b $ay(tbw).mybutton
# if the button does not already exist:
if { ![winfo exists $b] } {
  # create it:
  button $b -padx 0 -pady 0 -image myImage -command myCommand
  # tell Ayam about the new button:
  # you can use "linsert", to insert the button in a specific
  # place or just append to the end of the list using "lappend"
  lappend ay(toolbuttons) mybutton
  # display the button:
  toolbox_layout
  # from now on, the button will be under the
  # automatic toolbox layout management
}
Cet exemple montre que :
  1. Les boutons de la boîte à outils doivent être créés dans un cadre dont le chemin et le nom de la fenêtre sont stockés dans la variable globale "ay(tbw)" (il s'agit de ".tbw.f" pour les configurations d'interface graphique multi-fenêtres ou ".fv.fTools.f" pour les configurations d'interface graphique à fenêtre unique),
  2. Ayam gère une liste de tous les boutons de la boîte à outils dans la variable globale "ay(toolbuttons)", l'ordre dans cette liste est l'ordre dans lequel les boutons apparaissent dans la boîte à outils,
  3. la gestion automatique de la mise en page est effectuée par la procédure "toolbox_layout".

L'ajout de boutons ne comportant que du texte est un peu plus compliqué, car la taille de ces boutons ne s'intègre pas toujours bien dans le schéma des boutons à icônes, dont la taille est constante. Cependant, la procédure "toolbox_add" peut être d'une aide considérable.[∗]

Voir aussi le script "scripts/topoly.tcl" pour un exemple.

Le script d'exemple suivant ajoute deux boutons au bas de la boîte à outils couvrant toute la fenêtre (cela fonctionne mieux avec la disposition standard de la boîte à outils de 4 par 12 boutons utilisée dans la configuration de l'interface graphique multi-fenêtres) : 

global ay
# create a frame:
set f [frame $ay(tbw).fcollex]
# calculate the row number below the last row:
set row [expr [lindex [grid size $ay(tbw)] 1] + 1]
# now display the frame at calculated row, spanning the whole window:
grid $f -row $row -column 0 -columnspan [lindex [grid size $ay(tbw)] 0]\
     -sticky we
# create two buttons inside the frame:
button $f.b1 -width 5 -text "Coll." -command { collMP; rV; }
button $f.b2 -width 5 -text "Expl." -command { explMP; rV; }
pack $f.b1 $f.b2 -side left -fill x -expand yes

6.5 Scripts d'aide distribués

Cette section contient la documentation de certains scripts d'aide qui sont distribués avec Ayam.

Les scripts d'aide peuvent être exécutés via le menu contextuel de la console, la commande Tcl "source" dans la console, ou le paramètre de préférence "Scripts" de Ayam à chaque démarrage (ce dernier à l'exception des scripts dits external "repairAyam.tcl", "bgconvert.tcl", et "aytest.tcl").

Tous les autres scripts interne peuvent être combinés arbitrairement, à l'exception de "kdialog.tcl", "zdialog.tcl", et "intfd.tcl", qui sont mutuellement exclusifs.

Réparer Ayam

Le script externe Tcl "repairAyam.tcl" peut être utilisé pour réparer l'état de l'application Ayam, si elle est bloquée, par exemple, dans une boucle sans fin de messages d'erreur Tcl.[∗]

Sur les systèmes Unix, "repairAyam" peut être lancé depuis n'importe quel shell en tapant simplement :

» ./repairAyam.tcl
ou
» wish repairAyam.tcl
à l'invite de commande ; si le script détecte qu'il fonctionne sous Unix et non en Ayam, il s'enverra à l'interprète Tcl qu'Ayam utilise en utilisant la commande Tk send. Sous Mac OS X Aqua (pas X11 !), les événements AppleScript seront utilisés à la place de la commande Tk send. Si cela ne fonctionne pas comme prévu, "repairAyam.tcl" peut toujours être lancé via la console Ayam (comme sur Win32).

Sur Win32 "repairAyam.tcl" doit être lancé depuis la console Ayam à l'aide de la commande :

» source scripts/repairAyam.tcl
ou via le menu contextuel des consoles : "Console/Load File".

Le script "repairAyam.tcl" doit être considéré comme un dernier recours pour aider à sauvegarder l'état actuel des objets modifiés.

Le script va fermer toutes les vues, nettoyer les variables d'état de l'application, réinitialiser le curseur de la souris et l'invite de la console, et essayer de mettre à jour les widgets importants de la fenêtre principale.

De plus, le script va également vider la console et essayer de briser d'éventuelles boucles sans fin en cours d'exécution, par exemple dans la console ou dans les objets du script.[∗]

A Après avoir exécuté "repairAyam.tcl" la scène (ou les objets les plus importants sur lesquels on travaille actuellement) devrait être immédiatement sauvegardée dans un nouveau fichier de scène, mais pas le fichier actuellement chargé, en utilisant "File/Save As" ou "Special/Save Selected") et Ayam devrait être redémarré après.

La simple sauvegarde de la scène en utilisant "File/Save" ou <Ctrl+s> doit être évitée car les vues ont peut-être été supprimées.

Tester Ayam

Le script external "aytest.tcl" permet de tester l'implémentation de Ayam en créant des objets avec diverses combinaisons de paramètres et en exécutant des opérations standard et des actions de modélisation sur ceux-ci.

Utiliser Ayam comme convertisseur de ligne de commande

Le script externe Tcl "bgconvert.tcl" convertit les fichiers de scènes d'un format de fichier 3D à un autre, avec l'aide de Ayam qui tourne en arrière-plan.[∗]

Dans sa forme la plus simple, bgconvert peut être utilisé à partir d'une ligne de commande Unix (ou d'un script shell) comme ceci :

» bgconvert.tcl infile.x3d outfile.dxf

La commande ci-dessus chargerait le fichier X3D "infile.x3d" dans Ayam et exporterait la scène sous forme de fichier DXF vers "outfile.dxf".

Pour une conversion réussie, Ayam doit fonctionner et les plugins requis pour les processus d'importation et d'exportation doivent être disponibles et correctement configurés (vérifiez le paramètre de préférence "Plugins"). Les plugins nécessaires à la conversion seront chargés automatiquement.

Des options d'importation et d'exportation peuvent également être données de cette manière :

» bgconvert.tcl "infile.rib -p 1" outfile.dxf

Dans l'exemple ci-dessus, l'option "-p 1" active la lecture des fichiers RIB partiels.

Les options disponibles et leur syntaxe peuvent être demandées aux scripts Tcl des plugins d'importation et d'exportation (par exemple : "plugins/rrib.tcl").

Analyse des ombrages (shaders)

Le script Tcl "slxml.tcl" permet à la machine d'analyse des ombrages de Ayam de reconnaître les méta-informations basées sur XML intégrées dans les commentaires du langage de shading.[∗] De cette façon, la base de données des ombres pour les objets Material peut être constituée à partir de fichiers sources en langue de shading, au lieu d'ombres compilées.
Les balises XML ne seront pas analysées par un véritable analyseur XML, de sorte qu'il n'y a pas de problème de forme. Toutefois, les attributs doivent être ordonnés d'une certaine manière. Pour spécifier une ombre, utilisez : 

<shader type="stype" name="sname">
où stype est l'un des noms suivants : surface, displacement, volume, light, imager, ou transformation et sname est le nom de l'ombre qui doit également correspondre au nom du fichier source de l'ombre sans extension.

Pour spécifier un paramètre d'ombre, utilisez une ligne du type : 

<argument name="argname" type="argtype" value="argval">
où argname est le nom du paramètre, argtype est à choisir parmi float, string, matrix, color, point, normal, ou vector et argval est la valeur par défaut.

Voir également l'exemple suivant de source d'ombre : 

/* myshader.sl:
 *  Author: Randolf Schultz
 * <shader type="surface" name="myshader">
 * <argument name="Ka" type="float" value="0.5">
 * <argument name="Kd" type="float" value="0.9">
 * <argument name="ic" type="color" value="0 1 0">
 */
surface myshader(float Ka = 0.5, Kd = 0.9; color ic = color (0, 1, 0);)
{
  color mycolor;
  ...
  Ci = Cs*mycolor*(Ka*ambient()+Kd*diffuse(faceforward(normalize(N),I)));
}

Les restrictions/limites suivantes (par opposition à l'analyse normale des ombres) s'appliquent :

Tout transformer en polygones

Le script "topoly.tcl" parcourt récursivement la scène et convertit tout en une représentation polygonale.[∗]

Après l'exécution du script, il y a un nouveau bouton dans la boîte à outils nommé "ToPolyMesh". De plus, il y a une entrée correspondante dans le menu principal "Custom". En appuyant sur le bouton ou en utilisant l'entrée de menu, le processus de conversion démarre immédiatement.

Comme les modifications de la conversion ne peuvent pas être annulées, la conversion ne sera pas exécutée si la scène contient des modifications non sauvegardées.

La conversion utilisera les paramètres actuels des paramètres de préférence "SMethod", "SParamU", et "SParamV" ; les balises "TP" (si présentes) remplaceront ces paramètres. Les balises TP peuvent être créées facilement à l'aide de l'outil de tessellation, Voir aussi la section Outil de tessellation (triangularisation).

Tout transformer en patch NURBS

Le script "tonpatch.tcl" parcourt récursivement la scène et convertit tout en une représentation patch NURBS, aplatissant ainsi la hiérarchie des objets de l'outil.[∗]

Après l'exécution du script, il y a un nouveau bouton dans la boîte à outils nommé "ToNPatch". De plus, il y a une entrée correspondante dans le menu principal "Custom". En appuyant sur le bouton ou en utilisant l'entrée de menu, le processus de conversion démarre immédiatement.

Comme les modifications de la conversion ne peuvent pas être annulées, la conversion ne sera pas exécutée si la scène contient des modifications non enregistrées.

Restreindre la console

Le script "2lcons.tcl" (pour une console à deux lignes) peut être utilisé pour restreindre l'espace occupé par la console à l'écran.

Normalement, la console Ayam est redimensionnée avec la fenêtre principale et occupe une quantité variable d'espace sur l'écran. Après l'exécution du script, la console sera toujours redimensionnée à exactement deux lignes de texte. Différentes valeurs peuvent être choisies facilement en adaptant le script.

Colorer la bague de mise au point (????focus ring)

Le script "colfocus.tcl" (pour colored focus) peut être utilisé pour peindre la bague de mise au point dans une couleur plus visible.

Après l'exécution du script, l'anneau de mise au point sera peint en bleu (au lieu du noir) : les sous-fenêtres de mise au point (vues, console, arbre d'objets) seront plus facilement reconnaissables. D'autres couleurs peuvent être utilisées en éditant le script.

Automatismes avec les actions de centrage (???? Automatic About Center Actions)

Le script "aac.tcl" (pour aautomatique about center) peut être utilisé pour passer automatiquement toutes les actions de modélisation à leurs variantes environnantes avec la marque placée au centre de la sélection actuelle.

Après avoir exécuté le script, invoquer par exemple l'action d'échelle 2D en utilisant le raccourci <s> permettra :

Le script modifie toutes les actions de rotation et d'échelle (y compris leurs variantes limitées à l'axe).

Notez que la marque n'est pas réinitialisée à un nouveau centre, lorsque la sélection change. Après un changement de sélection (par exemple en sélectionnant des points dans une vue différente), il suffit de relancer l'action pour transformer à partir du nouveau centre.

Pour effectuer une rotation ou une mise à l'échelle autour d'un point différent du centre, la marque peut toujours être placée manuellement en utilisant <a>.

Pour désactiver temporairement le comportement modifié, le raccourci clavier global <F11> peut être utilisé.

Automatisation des actions sur les points

Le script "apnt.tcl" (pour aautomatic point) peut être utilisé pour passer automatiquement en mode de modélisation ponctuelle après une sélection de points.

Après l'exécution du script, la sélection (marquage) d'un point à l'aide de l'action "Sélectionner un point" (raccourci <t>) fera automatiquement basculer la vue vers la modélisation de points, de sorte que les prochaines actions de modélisation (par exemple, déplacer, via le raccourci <m>) transformeront toujours les points et ne modifieront pas les transformations des objets. Notez qu'actuellement, le passage à la modélisation par points se fera également, si aucun point n'est effectivement sélectionné, c'est juste le clic de la souris qui compte.

La sélection de tous les points via le raccourci clavier <A> permet en outre de passer à la modélisation de points et la désélection de tous les points via <N> permet en outre de passer à la modélisation d'objets.[∗]

Il est également toujours possible de revenir à la modélisation d'objets à tout moment via le raccourci clavier <o>.

Pour désactiver temporairement le comportement modifié, le raccourci clavier global <F12> peut être utilisé.

Sauvegarder les points sélectionnés

Le script "ssp.tcl" (pour save selected ppoints) permet d'enregistrer la sélection de points sur des balises de type SP.[∗]

Après l'exécution du script, deux nouveaux boutons apparaissent dans la boîte à outils qui permettent respectivement de sauvegarder et de restaurer la sélection de points. Voir également le tableau ci-dessous.

OperationIcon
Save
Restore

Sauve/restaure les points sélectionnés

Il y a également deux entrées correspondantes dans le menu personnalisé.

Notez que les balises peuvent être enregistrées dans des fichiers de scène et également copiées sur différents objets.

Modifier le comportement des touches curseur

Le script "rc.tcl" (pour revert cursor) peut être utilisé pour obtenir un comportement plus utile de la touche curseur dans les vues de modélisation primaires (vues parallèles).

Après l'exécution du script, les raccourcis clavier pour la rotation et le panoramique dans des vues parallèles sont permutés, par exemple, il suffit d'appuyer sur la touche <Left> pour effectuer un panoramique de la vue, au lieu de la faire tourner.

Les raccourcis seront à nouveau échangés, lorsque la vue changera de type pour devenir "Perspective".

Accéder aux fonctions de base à partir de la boîte à outils

Le script "zap.tcl" montre comment une fonctionnalité de base arbitraire, qui n'est disponible que par une entrée du menu principal ou l'interface de script, peut être facilement accessible via la fenêtre de la boîte à outils.

Après l'exécution du script "zap.tcl", il y aura un nouveau bouton de la boîte à outils, appelé "Zap !", qui lance simplement la commande zap (qui iconifie l'application complète).

Passer des dialogues à Kdialog

Le script "kdialog.tcl" permet à tous les dialogues de fichiers de Ayam d'utiliser l'application kdialog du projet KDE au lieu du dialogue de fichiers Tk natif.
Le script ajoute également une entrée personnalisée dans le menu principal pour annuler tout changement.

Passez des dialogues à Zenity

Le script "zdialog.tcl" bascule tous les dialogues de fichiers de Ayam pour utiliser l'application zenity du projet Gnome au lieu du dialogue de fichiers Tk natif.
Le script ajoute également une entrée personnalisée dans le menu principal pour annuler tout changement.

Changer les dialogues de fichiers en Tcl

Le script "intfd.tcl" fait passer tous les dialogues de fichiers de Ayam à la version interne de Tcl/Tk au lieu des dialogues de fichiers natifs fournis par le système d'exploitation.

Utiliser Aqsis à partir du répertoire des applications

Le script "useaqsisapp.tcl" configure Ayam pour utiliser Aqsis à partir de la structure du répertoire des applications ("/Applications/Aqsis.app") sur Mac OS X. C'est l'emplacement d'installation par défaut d'Aqsis sur Mac OS X.

Le script adapte les chemins de recherche des exécutables et des ombres. De plus, les variables d'environnement vitales pour le fonctionnement d'Aqsis seront correctement configurées.

Notez que le script ne change pas les préférences "RIB-Export/Renderer", vous devez toujours passer à Aqsis en utilisant le menu principal "Special/Select Renderer" une fois.

Utiliser Pixie depuis le répertoire de la bibliothèque

Le script "usepixie.tcl" configure Ayam pour utiliser Pixie depuis le répertoire "/Library/pixie" sous Mac OS X. C'est l'emplacement d'installation par défaut de Pixie sur Mac OS X.

Le script adapte les chemins de recherche de l'exécutable, de la bibliothèque partagée et des ombres. De plus, les variables d'environnement vitales pour le fonctionnement de Pixie seront correctement configurées.

Notez que le script ne modifie pas les préférences "RIB-Export/Renderer", vous devez toujours passer à Pixie en utilisant le menu principal "Special/Select Renderer" une fois.

Remplacer les Icones

Le script "myicons.tcl" permet de remplacer les icones de l'interface utilisateur Ayam, par exemple les icones de la boîte à outils, par des icones définies par l'utilisateur. Les nouveaux icones doivent être des fichiers images GIF de taille 25 par 25 et résider dans le répertoire "icons" relatif à l'exécutable Ayam. Les noms des fichiers d'images peuvent être obtenus à partir du script ou par la commande suivante de l'interface de script (dans la console Ayam) :

» image names
Des variants d'icones d'action (par exemple pour l'échelle relative aux actions) peuvent également être créés automatiquement en modifiant la variable "createVariants" dans le fichier de script.

Arbre dynamique

Le script "dtree.tcl" (arbre dynamique/rapide) remplace une partie du code de l'arbre BWidgets pour une interaction plus rapide dans les scènes avec de nombreux objets. Le widget d'arbre BWidget original (et le code de script qui l'accompagne en Ayam) crée un élément de canevas pour chaque objet de la scène, même s'il n'est pas visible dans le widget d'arbre. Par conséquent, les opérations de mise à jour de l'arbre qui ont lieu, par exemple, après le chargement d'une scène ou après des opérations de glisser-déposer, peuvent devenir très lentes, lorsqu'une scène comporte de nombreux objets. Si le script d'arbre est actif, il n'y a qu'autant d'éléments de canevas qu'il y a de noeuds visibles dans la région de défilement actuelle. Par conséquent, le travail avec de nombreux objets dans de longues listes devient beaucoup plus rapide pour les opérations qui nécessitent des mises à jour de l'arbre. Cependant, les opérations telles que l'ouverture ou la fermeture de sous-arbres ou même le simple défilement dans l'arbre deviendront un peu plus lentes, car les éléments de canevas doivent être créés en continu.

Vue du sommet de contrôle

Exemple de vue du sommet de contrôle

Le script "cvview.tcl" (control sommet view) permet de visualiser les points de contrôle des objets de surface ou de courbe NURBS comme propriété, voir aussi l'image ci-dessus. Le script prend actuellement en charge les types d'objets suivants : NPatch, NCurve, IPatch, PatchMesh, ACurve, ICurve, BCurve, et SDCurve. En outre, les objets qui fournissent des objets NPatch/NCurve et qui affichent une entrée NPInfo/NCInfo dans leur propriété de paramètre sont également pris en charge.[∗] Si le script est chargé, il y a une nouvelle entrée dans le menu "Custom" qui permet d'ajouter une nouvelle propriété à une surface individuelle ou à un objet "Curve". La propriété "CVView" affiche tous les sommets de contrôle dans une grille régulière. Les coordonnées de chaque sommet seront affichées lorsque le pointeur de la souris le survole. Cela fonctionne également si les points de contrôle se regroupent dans l'espace 3D ou ont des valeurs inhabituelles. En outre, la sélection actuelle des points est visualisée en peignant les sommets sélectionnés en rouge et la sélection peut également être ajustée en cliquant sur les cercles. Il est également possible de faire glisser la sélection.[∗]

Tracé de la courbure

Exemple de tracé de la courbure

Le script "curvature.tcl" permet de visualiser la courbure des courbes NURBS et la courbe NURBS fournissant des objets comme propriété, voir aussi l'image ci-dessus. Si le script est chargé, il y a une nouvelle entrée dans le menu "Custom" qui permet d'ajouter une nouvelle propriété à un objet de courbe individuel. La nouvelle propriété affiche la courbure de la courbe sous la forme d'un diagramme interactif et en temps réel. Le diagramme sera mis à jour si la courbe change. Le diagramme peut être zoomé en le faisant glisser avec le bouton le plus à gauche de la souris et déplacé en le faisant glisser avec le bouton le plus à droite de la souris (en état zoomé). Le zoom est également possible à l'aide de la molette de la souris. L'état zoomé est transmis par l'ajout de "..." à l'étiquette correspondante de l'échelle horizontale. Notez que lors d'un panoramique, la nouvelle section de la courbe sera redimensionnée pour remplir complètement l'axe Y. Pour les objets de la courbe NURBS, la plage de valeurs réelles des noeuds sera affichée sur l'axe des x, tandis que pour les objets de la courbe NURBS fournissant des objets, une plage de valeurs relatives des noeuds ([0, 1]) sera affichée. Un clic sur l'étiquette "k" permet de basculer entre l'échelle absolue et l'échelle logarithmique de l'axe Y. Il y a une poignée de redimensionnement qui permet d'adapter la taille du diagramme au canevas des propriétés.

NURBS pour X3DOM

affichage de NURBS via X3dom

Le script "x3dom-nurbs" implémente les noeuds <NurbsPatchSurface> et <NurbsTrimmedSurface> X3D NURBS pour x3dom (voir http://www.x3dom.org/) en JavaScript.
Après le chargement de la scène dans le navigateur web, les surfaces NURBS de ces noeuds sont tesselées en noeuds <IndexedTriangleSet>. Cela permet de publier directement les modèles NURBS sur le web sans conversion préalable en une représentation polygonale, ce qui est lourd, rigide et entraîne une consommation de bande passante plus importante.

Le tessellateur est basé sur une idée et un exemple de code provenant de A. J. Chung et A. J. Field: "A Simple Recursive Tessellator for Adaptive Surface Triangulation" in Journal of Graphics Tools Vol. 5, Iss. 3, 2000.

La mise en oeuvre s'étend sur quatre fichiers de script :

Pour utiliser le tessellateur, il suffit d'ajouter ce qui suit à votre fichier XHTML après avoir inclus "x3dom.js": 
 <script type="text/javascript" src="x3dom-nurbs-pool.js"/>
 <script type="text/javascript" src="x3dom-nurbs-nodes.js"/>
Le tesselateur étant entièrement automatique, aucun autre réglage n'est nécessaire. Des fichiers XHTML appropriés peuvent être créés en utilisant l'exportation X3D en mode x3dom, voir la section Options d'exportation X3D.

Alors que le tessellateur fonctionne en arrière-plan, une représentation polygonale initiale qui est directement dérivée du polygone de contrôle de la surface NURBS est affichée. De plus, une invite d'occupation est affichée, voir aussi l'image ci-dessous. Comme l'invite d'occupation est dérivée de l'invite de chargement de x3dom, elle peut également être stylisée avec le "x3dom-progress" style dans "x3dom.css".

Prompt X3dom NURBS Occupée

Le pavement fonctionne avec des "webworkers", des processus qui s'exécutent parallèlement au fil principal du navigateur, afin de ne pas bloquer l'interaction de l'utilisateur et d'utiliser des processeurs multicoeurs. Le pool de webworkers est actuellement codé en dur pour n'utiliser que trois de ces webworkers à la fois. Cette valeur peut être facilement adaptée dans "x3dom-nurbs-pool.js" (par exemple si votre CPU cible moyenne a plus de coeurs). Notez que chaque webworker pavera une seule surface NURBS, c'est-à-dire que les scènes avec une seule surface ne bénéficieront pas du parallélisme. Par défaut, le tessellateur tente de créer un pavage qui représente toutes les caractéristiques importantes de la surface de manière à ce qu'une inspection visuelle de moyenne à proche distance ne révèle pas la nature de la représentation triangulaire sous-jacente. Cela peut être trop fin/lent pour des objets qui ne sont jamais vus de près ou trop grossier pour des objets très détaillés. Par conséquent, et en accord avec les suggestions respectives de la spécification X3D, la qualité et la vitesse du pavement peuvent être ajustées à l'aide des attributs "uTessellation" et "vTessellation" des noeuds <NurbsPatchSurface> ou <NurbsTrimmedSurface> comme expliqué dans les sections suivantes.

Échantillonnage basé sur l'espace objet

Si aucun attribut "uTessellation" n'est spécifié, ou si sa valeur est positive, le tessellateur utilise le mode dit object space sampling. Dans ce mode, le tessellateur subdivise un ensemble initial de triangles de manière récursive jusqu'à ce que tous les bords de ces triangles soient plus courts qu'une valeur seuil donnée (dans l'espace objet). La valeur seuil est réglée automatiquement de manière à ce qu'un objet s'étendant d'une unité par une unité dans l'espace objet soit subdivisé à environ 15 par 15 par deux triangles. La valeur de l'attribut "uTessellation" est simplement multipliée dans ce seuil déterminé automatiquement. Par conséquent, les valeurs de "uTessellation" supérieures à 1.0 conduisent à une chaussée plus grossière et plus rapide, tandis que les valeurs inférieures à 1.0 conduisent à une chaussée plus fine et plus lente. Notez que dans ce mode, la valeur de l'attribut "vTessellation" n'est pas considérée du tout. Notez également que dans les régions fortement courbées de la surface et aux bords de coupe, des triangles encore plus petits que ceux déterminés par le critère de longueur de bord peuvent être créés.

Échantillonnage basé sur l'espace paramétrique

Si la valeur de l'attribut "uTessellation" est négative, le tessellateur passe à un échantillonnage spatial paramétrique. Dans ce mode, l'attribut "vTessellation" est également pris en compte. Comme dans le mode d'échantillonnage de l'espace objet, une valeur seuil automatique est calculée, mais ici, l'extension de l'objet dans l'espace paramétrique (c'est-à-dire le nombre de points de contrôle) est utilisée. Cela donne en fait deux valeurs seuils, une pour chaque dimension paramétrique. Les attributs "uTessellation" et "vTessellation" sont multipliés dans ces seuils. Par conséquent, les valeurs supérieures à -1.0 (en valeur absolue) conduisent à un pavement plus grossier et plus rapide dans la dimension respective. Les valeurs inférieures à -1.0 (en valeur absolue) conduisent à un pavement fin et plus lent dans la dimension respective. Cela signifie qu'une valeur de -2.0 entraîne environ la moitié du nombre de triangles par rapport à la valeur par défaut et qu'une valeur de -0.5 entraîne deux fois plus de triangles par rapport à la valeur par défaut dans la dimension paramétrique respective. Comme le calcul de la longueur des bords est plus simple et qu'aucune analyse de courbure n'est effectuée, l'échantillonnage paramétrique de l'espace est considérablement plus rapide que l'échantillonnage de l'espace de l'objet. Notez qu'aux bords de la courbe de coupe, des triangles encore plus petits que ceux déterminés par le critère de longueur de bord peuvent être créés.

Attributs additionnels

Pour faciliter le paramétrage des attributs "uTessellation" et "vTessellation", un attribut "normalPerSommet" peut être ajouté au noeud respectif <NurbsPatchSurface> ou <NurbsTrimmedSurface>. Cet attribut sera alors également défini pour le noeud <IndexedTriangleSet> correspondant qui est créé par le tessellateur. Si la valeur de cet attribut est "false", x3dom affichera cette surface dans un style ombré plat et les triangles de tesselé seront visibles, ce qui permettra de juger et d'ajuster plus facilement la qualité de la tessellation.

Restrictions et lacunes dans la mise en oeuvre

En raison de la mémorisation des points de surface, les valeurs paramétriques ne doivent pas dépasser :

1,7976931348623157·10308 / 10·1010 = 1,7976931348623157·10297

Les coordonnées de la texture sont toujours directement dérivées des valeurs paramétriques. Les normales de surface ne sont pas calculées par le tessellateur, mais par x3dom. Cela peut conduire à des normales qui sont fausses pour des pavements très grossiers mais qui sont beaucoup plus rapides. Un autre avantage de cette approche est que les normales en des points de surface non différentiables (par exemple les pôles de la sphère standard NURBS) ne s'inversent pas. Il n'y a pas de prise en charge pour les noeuds suivants :

6.6 Objets script distribués

Ces scripts mettent en oeuvre des objets Script, Voir aussi la section L'objet Script.

Cône tronqué

Cône tronqué avec ZMax 2.0

Le fichier "tcone.tcl" est un script objet Script qui crée des cônes tronqués avec des arguments similaires à la primitive cylindre, voir aussi l'image ci-dessus.

Ce script doit être utilisé dans un objet Script de type "Create" (voir section L'objet Script).

Pour plus de commodité, il existe également une interface graphique de propriété ; il faut ajouter une balise "NP" de valeur "TConeAttr" à l'objet Script pour la voir.

Les paramètres du cône tronqué sont :

Un exemple de fichier de scène contenant un tel objet est distribué avec Ayam, voir le fichier :
"ayam/scn/scripts/tcone.ay".

Boîte avec topologie cylindrique

Boîte avec topologie cylindrique

Le fichier "cbox.tcl" est un script objet Script qui crée une surface NURBS sous la forme d'une boîte à topologie cylindrique, voir aussi l'image ci-dessus.

Ce script doit être utilisé dans un objet Script de type "Create" (voir section L'objet Script).

Pour plus de commodité, il existe également une interface graphique de propriété ; il faut ajouter une balise "NP" de valeur "CBoxAttr" à l'objet Script pour la voir.

Les paramètres de la boîte cylindrique sont :

Contrairement à l'objet Box standard, la boîte cylindrique se transforme en un seul patch NURBS. Cependant, ce patch a des pôles et, par conséquent, des défauts d'ombrage peuvent apparaître sur les côtés supérieur et inférieur. Il est également difficile de texturer cet objet. Un exemple de fichier de scène contenant un tel objet est distribué avec Ayam, voir le fichier :
"ayam/scn/scripts/cbox.ay".

Cercle NURBS avec base triangulaire

Cercle NURBS avec base triangulaire

Le fichier "tcircle.tcl" est un script objet qui crée des cercles NURBS avec une base triangulaire, voir aussi l'image ci-dessus.

Contrairement au cercle NURBS standard de neuf points à base rectangulaire, le cercle triangulaire ne comporte que sept points de contrôle. Cela permet d'économiser de la mémoire, par exemple dans le cas d'objets à balayage long. Cependant, le paramétrage du cercle triangulaire est également légèrement moins bon. En outre, seuls les cercles complets qui commencent sur l'axe X positif sont pris en charge.

Ce script doit être utilisé dans un objet Script de type "Create" (voir section L'objet Script).

Pour plus de commodité, il existe également une interface graphique de propriété ; il faut ajouter une balise "NP" de valeur "TCircleAttr" à l'objet Script pour la voir.

Le paramètre du cercle triangulaire est :

Un exemple de fichier de scène contenant un tel objet est distribué avec Ayam, voir le fichier :
"ayam/scn/scripts/tcircle.ay".

Hélicoïde (helix)

Exemple d'hélicoïde

Le script "helix.tcl" crée une courbe NURBS qui forme une hélicoïde, voir aussi l'image ci-dessus.

Ce script doit être utilisé dans un objet Script de type "Create" (voir section L'objet Script).

Une interface graphique de propriété est également fournie ; il faut ajouter une balise "NP" de valeur "HelixAttr" à l'objet Script pour la voir.

Les paramètres de l'hélicoïde sont :

Un exemple de fichier de scène contenant un tel objet est distribué avec Ayam, voir le fichier :
"ayam/scn/scripts/helix.ay".

Spirale

Exemple de spirale

Le script "spiral.tcl" crée une courbe NURBS qui forme une spirale, voir aussi l'image ci-dessus.

Ce script doit être utilisé dans un objet Script de type "Create" (voir section L'objet Script).

Une interface graphique de propriété est également fournie ; il faut ajouter une balise "NP" de valeur "SpiralAttr" à l'objet Script pour le voir.

Les paramètres de la spirale sont :

Un exemple de fichier de scène contenant un tel objet est distribué avec Ayam, voir le fichier :
"ayam/scn/scripts/spiral.ay".

Double balayage (DualSweep)

Exemle de double balayage

Le fichier "dualsweep.tcl" est un script objet Script qui crée une surface NURBS à partir de trois courbes paramètres similaires au birailing mais avec des courbes de section transversale perpendiculaires aux deux rails, voir aussi l'image ci-dessus.

La première courbe est dite section transversale (cross section). Cette courbe doit être plane et définie dans le plan YZ. C'est la courbe ouverte la plus à gauche dans l'image de l'exemple ci-dessus.
La deuxième courbe est la première courbe rail. Cette courbe doit commencer au point de départ de la courbe de la section transversale. C'est la courbe fermée inférieure dans l'image de l'exemple ci-dessus.
La troisième courbe de paramètres est la deuxième courbe rail. Cette courbe doit commencer au point final de la courbe de la section transversale. C'est la courbe fermée supérieure dans l'image de l'exemple ci-dessus.

Ce script doit être utilisé dans un objet Script de type "Modify" (voir section L'objet Script).

Pour plus de commodité, il existe également une interface graphique de propriété ; il faut ajouter une balise "NP" de valeur "DualSweepAttr" à l'objet Script pour le voir.

Les paramètres du double balayage sont :

Un exemple de fichier de scène contenant un tel objet est distribué avec Ayam, voir le fichier :
"ayam/scn/scripts/dualsweep.ay".

Surface par translation

Exemple de surface par translation

Le script "tsurf.tcl" crée une surface par translation à partir de deux courbes de paramètres, voir aussi l'image ci-dessus. Les points de contrôle de la surface par translation sont créés en copiant les points de contrôle de la première courbe n fois, où n est le nombre de points de contrôle de la seconde courbe, tout en décalant également les points en fonction du décalage du point de contrôle nth au premier point de contrôle de la seconde courbe.

Les courbes n'ont pas besoin de se toucher en un point quelconque, mais si elles commencent au même point, la surface par translation interpolera les deux courbes.

Les courbes de paramètres rationnelles ne sont actuellement pas prises en charge.

Ce script doit être utilisé dans un objet Script de type "Modify" (voir section L'objet Script).

Comme la surface est entièrement définie par les courbes de paramètres, il n'y a pas de paramètres supplémentaires et, par conséquent, il n'y a pas non plus d'interface graphique de propriétés.

Un exemple de fichier de scène contenant un tel objet est distribué avec Ayam, voir le fichier :
"ayam/scn/scripts/tsurf.ay".

Extrusion le long de la normale

Exemple d'extrusion le long de la normale

Le script "extruden.tcl" extrude une courbe NURBS le long de sa normale, voir aussi l'image ci-dessus.
Si l'objet courbe a une balise MN, celle-ci aura la priorité sur le calcul normal via "getPlaneNormal". Cela est plus rapide et permet également de créer des extrusions cisaillées.[∗]

En interne, le script crée une peau à partir de deux courbes, donc des courbes arbitrairement orientées et non planes sont prises en charge.

Ce script doit être utilisé dans un objet Script de type "Modify" (voir section L'objet Script).

Pour plus de commodité, il existe également une interface graphique de propriété ; il faut ajouter une balise "NP" de valeur "ExtrudeNAttr" à l'objet Script pour le voir.

Le paramètre de l'extrusion est :

Un exemple de fichier de scène contenant un tel objet est distribué avec Ayam, voir le fichier :
"ayam/scn/scripts/extruden.ay".

Créer des polyèdres à partir des notations de Conway

Polyèdre généré à partir de la notation Conway : "jtD"

Depuis Ayam 1.18, il existe un script d'exemple complet pour l'interface de script JavaScript distribué sous la forme "polyhedron.js" qui crée des polyèdres à partir de notations Conway. Le script est basé sur le générateur "VRML Polyhedron" en ligne de George W. Hart:
http://www.georgehart.com/virtual-polyhedra/conway_notation.html

Ce script doit être utilisé dans un objet Script de type "Create" (voir section L'objet Script).

Pour plus de commodité, il existe également une interface graphique de propriété ; pour rendre cette interface visible, une balise "NP" de valeur "PolyhedronAttr" doit être ajoutée à l'objet Script.

La notation Conway définit un ensemble d'opérations exécutées consécutivement sur une graine / forme de base. Le script supporte actuellement les graines et opérations suivantes (informations tirées des pages web de George W. Harts, voir ci-dessus).

Seeds:
Les solides de Platon sont désignés par les lettres T, O, C, I et D, selon leur première lettre. Les autres polyèdres qui sont mis en oeuvre ici comprennent les prismes : Pn, antiprismes : An, et les pyramides : Yn, où n est un nombre (3 ou plus) qui doit être spécifié pour indiquer la taille de la base, par exemple, Y3=T, P4=C, et A3=O.

Operations:
Actuellement, d, t, k, a, j, s, g, e, b, o, m, r et p sont définis. Ils sont alimentés par les opérations nécessaires pour créer les solides d'Archimède et leurs équivalents à partir des solides de Platon. Les tableaux suivants expliquent les opérations plus en détail :

LetterNameDescription
ddual Le double d'un polyèdre a un sommet pour chaque face, et une face pour chaque sommet, du polyèdre original, par exemple dC=O.
t / tntruncate all / just n-fold vertices La troncature d'un polyèdre coupe chaque sommet, produisant une nouvelle face n fois orientée pour chaque sommet n fois dupliqué. (????)
k / knkis all / just n-sided faces L'opération kis divise chaque face n fois orientée en n triangles. Un nouveau sommet est ajouté au centre de chaque face.
aambo On peut considérer que l'opération "Ambo" se limite aux points médians de la bordure. Elle produit un polyèdre, aX, avec un sommet pour chaque bord de X.
jjoin L'opérateur "join" est dual de "ambo", donc jX=dadX=daX.jX est comme kX sans les bords originaux de X.
eexpand Chaque face de X est séparée de toutes ses voisines et reconnectée avec une nouvelle face à 4 côtés, correspondant à un bord de X.Un n-polygone (????) est ensuite ajouté pour relier les faces quadrilatérales à chaque sommet n-fold.
ssnub L'opération de "snub" peut être considérée comme une opération "eC" suivie d'une opération de découpage de chacune des nouvelles faces quadruples le long d'une diagonale en deux triangles.Grâce à la maniabilité de ces coupes, tous les sommets de "sX" sont quintuplés.
ggyro L'opération duale à s est g.g est comme k mais avec les nouvelles arêtes reliant les centres des faces aux points 1/3 des arêtes plutôt qu'aux sommets.
bbevel L'opération de biseau peut être définie par bX=taX.
oortho Dual à e, oX=deX=jjX.oX a pour effet de placer de nouveaux sommets au milieu de chaque face de X et de les relier, avec de nouvelles arêtes, aux points médians des arêtes de X.
mmeta Dual à b, m est comme k et o combinés ; de nouvelles arêtes relient les nouveaux sommets au centre des faces aux anciens sommets et les nouveaux sommets aux points médians des arêtes.

Opérations en notation de Conway

LetterNameDescription
rreflect Transforme un solide de gauche en solide de droite, ou inversement, mais n'a aucun effet sur un solide réflexif.Donc rC=C, mais comparez sC et rsC.
ppropellor Fait de chaque face de n-polygone une "hélice" de n-polygone entourée de n quadrilatères, par exemple, pT est l'icosaèdre tétraédrique stellé.Essayez pkD et pt6kT.p est une opération auto-duale, c'est-à-dire dpdX=pX et dpX=pdX, et p fait également la navette avec a et j, c'est-à-dire paX=apX.

Opérations additionnelles

Ces explications abrégées sont à nouveau tirées de George W. Hart.

6.7 Interface de script JavaScript

Cette section contient la documentation de l'interface de script JavaScript qui est disponible après le chargement du plugin "jsinterp".

L'interface de script JavaScript existe depuis Ayam 1.18 et est basée sur le moteur JavaScript de Mozilla SpiderMonkey.

Au chargement, le plugin "jsinterp" crée un contexte JavaScript qui existe (avec toutes les variables et objets qui y sont définis) jusqu'à la sortie de Ayam.

Accès à JavaScript depuis Tcl et les objets Script

La fonctionnalité JavaScript est accessible depuis l'interface de script Tcl via la commande "jsEval". La commande peut être utilisée soit pour exécuter directement le code JavaScript fourni via l'argument de commandes (code Tcl en gras) :

» jsEval {var a = 0; a = a + 5.5; tclset("a", a);}
ou pour exécuter du code JavaScript à partir d'un fichier :
» jsEval -f scriptfile.js
Notez que cette commande n'est pas disponible dans l'interpréteur sécurisé. En outre, les objets script peuvent également être implémentés en JavaScript, à condition que la première ligne du script soit un commentaire qui indique à Ayam d'utiliser l'interpréteur JavaScript :
/* Ayam, use: JavaScript */
var a = 0;
...
Notez que le contexte de script JavaScript hérite des limitations du contexte Tcl appelant. Par exemple, lors de l'exécution d'un objet Script, le code suivant échoue :
tcleval("exit");
parce que la commande Tcl "exit" n'est pas disponible dans l'interpréteur sécurisé. La commande n'échouera pas, lorsque le contexte d'appel est l'interpréteur Tcl principal ; on peut par exemple taper dans la console Ayam :
» jsEval {tcleval("exit");}
and Ayam quits (Voir aussi la section: Interpréteur sécurisé).

Fonctions JavaScript

Cette sous-section renseigne sur les fonctions globales supplémentaires disponibles dans l'interpréteur JavaScript Ayam.

Il s'agit de commandes Tcl converties (par exemple : "crtOb()"), "tcleval()", "tclvar()", et "tclset()".

Commandes converties :
La fonctionnalité de Ayam est accessible à partir de JavaScript via un ensemble plus large de fonctions globales, appelées commandes Tcl correspondantes. Par exemple, les objets Ayam peuvent être créés en JavaScript en utilisant un appel de fonction comme celui-ci :

crtOb("NCircle");
or, with additional arguments:
crtOb("NCircle", "-radius", 3.0);
En général, toutes les commandes disponibles dans l'interpréteur Ayam Tcl sécurisé sont également disponibles comme fonction (voir la section Procédures and Commandes pour une liste plus ou moins complète de ces commandes).

Notez que les procédures Tcl ne sont généralement pas disponibles en tant que fonction JavaScript globale, mais elles peuvent être appelées en utilisant "tcleval()" comme indiqué dans le paragraphe suivant.

tcleval():
Cette fonction JavaScript globale permet d'évaluer des scripts Tcl quelconques, fournis en argument sous forme de chaîne :

var a = 42;
a = tcleval("puts " + a + "; return 5;");
tcleval("puts " + a);
/* résultat attendu : 42 5 */
La fonction "tcleval()" donne accès à toutes les fonctionnalités de Ayam qui sont juste disponibles en tant que procédure Tcl. Notez que les valeurs de retour sont correctement retransférées en JavaScript selon les règles de conversion des données comme documenté ci-dessous. Toutefois, en raison d'une conversion intermédiaire en données de chaîne, le surcoût d'un tel appel est considérable et le transport de données en masse doit être organisé par d'autres moyens, voir ci-dessous.

tclvar():
En utilisant la fonction JavaScript "tclvar()" un lien entre une variable Tcl et une variable correspondante dans le contexte JavaScript peut être établi. La fonction "tclvar()" crée essentiellement une trace d'écriture sur la variable Tcl, de sorte que les modifications du côté Tcl sont toujours automatiquement répercutées du côté JavaScript :

tclvar("a");
tcleval("set a 42");
tcleval("puts " + a);
/* résultat attendu : 42 */
Notez que la variable correspondante du côté JavaScript n' existe pas tant que la première opération d'écriture sur la variable Tcl se produise. La variable Tcl, à son tour, n'a pas besoin d'exister, lorsque la fonction "tclvar()" est appelée (c'est-à-dire que tout le travail est fait dans le rappel de trace). Si le nom de la variable contient un spécificateur d'espace de noms, cet espace de noms doit exister, lorsque la fonction "tclvar()" est appelée.

Bien qu'il semble parfaitement adapté, "tclvar()" ne peut pas être utilisé pour gérer un tableau de données de propriétés (si le tableau contient des composants à enregistrer dans des fichiers de scènes Ayam). En effet, à la lecture d'un fichier de scène contenant de tels éléments de tableau enregistrés, les éléments seront lus (et placés dans le contexte Tcl) avant que le script ne puisse établir la trace d'écriture à l'aide de "tclvar()" et les données du fichier de scène n'arriveront jamais dans le contexte JavaScript. Il n'y a pas de moyen facile de contourner ce problème. Une suggestion pour gérer un tableau de données de propriété est présentée dans la section d'exemples complets ci-dessous.

tclset():
La troisième fonction JavaScript globale est "tclset()" qui permet de définir efficacement les variables Tcl à partir du contexte JavaScript en évitant la conversion en données chaîne et inversement. Par exemple :

var a = 3.3;
var b = new Array(1, 3, 5);
tclset("a", a);
tclset("b", b);
fixe la variable Tcl "a" à la valeur en virgule flottante 3.3, et "b" à une liste de valeurs entières { 1 3 5 }.
Notez que les noms de variables peuvent également pointer vers des éléments de tableau Tcl, par exemple
tclset("SphereAttrData(Radius)", 1.2);
définit l'élément Radius dans le tableau SphereAttrData ; ou contient des spécificateurs d'espace de noms, par exemple
tclset("::MyNameSpace::Radius", 1.2);
définit la variable Radius dans l'espace de noms MyNameSpace.

Conversion de données

Lorsque les données sont transférées du côté Tcl vers le côté JavaScript (par exemple lors de la conversion des valeurs de retour de "tcleval()" ou des valeurs de variables liées via "tclvar()"), les conversions suivantes sont en vigueur : Les types de données scalaires seront convertis en leurs équivalents directement correspondants, à l'exception des booléens, qui seront convertis en valeurs entières. Les listes seront converties en objets Array (l'imbrication est autorisée et produira des tableaux imbriqués en conséquence). Les tableaux associatifs seront convertis en objets ayant des propriétés nommées. Les chaînes Unicode ne sont actuellement pas prises en charge. Voir également le tableau ci-dessous.

TclJavaScript
Boolean (true, false)Integer (1, 0)
Integer (2)Integer (2)
Double (3.14)Double (3.14)
String ("mystr")String ("mystr")
List ({0 1 2})Array ((0, 1, 2))
Array (mya(mye) = 0.1)Object (mya.mye = 0.1)

Conversions de Tcl vers JavaScript

Lorsque des données sont transférées du côté JavaScript au côté Tcl (par exemple en tant qu'argument de fonction), les conversions suivantes sont en vigueur : Les types de données scalaires seront convertis en leurs équivalents directement correspondants, Les objets du tableau seront convertis en listes (l'imbrication est autorisée et produira des listes imbriquées en conséquence). Les chaînes Unicode et les objets d'un type autre que Array (par exemple booléen) ne sont actuellement pas pris en charge. Voir également le tableau suivant.

JavaScriptTcl
Integer (2)Integer (2)
Double (3.14)Double (3.14)
String ("mystr")String ("mystr")
Array ((0, 1, 2))List ({0 1 2})

Conversions de JavaScript vers Tcl

Le transport/la conversion des propriétés des objets (en éléments de tableaux associatifs, par exemple) peut être organisé manuellement de cette manière :

var a = new Object();
a.b = 3.14;
tclset("a(b)", a.b);

Exemples complets

Cette section contient deux exemples complets d'objets Script écrits en JavaScript.

Pour le premier exemple, utilisez le type d'objet Script "Modify" et mettez une sphère comme objet enfant de l'objet Script. 

/* Ayam, use: JavaScript */
tclvar("SphereAttrData");
getProp();
if(SphereAttrData)
{
  tclset("SphereAttrData(ZMin)", -SphereAttrData.Radius);
  tclset("SphereAttrData(ZMax)", SphereAttrData.Radius);
  setProp();
}
Le script ci-dessus permet de s'assurer que les paramètres ZMin et ZMax de l'objet Sphère correspondent toujours à son rayon. Tout d'abord, un lien est établi à partir du tableau de données des propriétés de l'objet Sphère original "SphereAttrData", de sorte que lorsque "getProp()" (une commande Tcl Ayam convertie) est appelé, l'objet JavaScript "SphereAttrData" est également rempli de données significatives.
La ligne suivante (le if) est une mesure de sécurité qui empêche l'échec du script si l'objet enfant de l'objet Script n'est pas un objet Sphere.
Maintenant, la valeur du rayon est retransférée à Tcl directement dans le tableau des données de propriété aux entrées ZMin et ZMax respectivement avec l'aide de "tclset()".
Enfin, la propriété modifiée est à nouveau transférée à l'objet Sphère avec une commande Tcl Ayam convertie "setProp()".

L'exemple suivant montre comment gérer une interface graphique de propriété dans un script objet Script implémenté en JavaScript. Utilisez le type d'objet Script "Create" et ajoutez une balise "NP MyProp" pour voir l'interface graphique de la propriété. 

/* Ayam, use: JavaScript, save array: MyPropData */
var MyPropData = new Object();
if(!tcleval("info exists MyPropData;"))
{
  /* initial script run (but not when loaded from scene file!) */
  MyPropData.MyItem = tcleval("set MyPropData(MyItem) 1.0;");
  tcleval("set MyPropData(SP) {MyItem};");
}
else
{
  /* all following script runs (and also when loaded from scene file!) */
  MyPropData.MyItem = tcleval("set MyPropData(MyItem);");
}
if(!tcleval("info exists MyPropGUI;"))
{
  tcleval("set ::phw [addPropertyGUI MyProp \"\" \"\"];");
  tcleval("addParam $::phw MyPropData MyItem;");
}
crtOb("Sphere");
sL();
getProp();
tclset("SphereAttrData(Radius)", MyPropData.MyItem);
tclset("SphereAttrData(ZMin)", -MyPropData.MyItem);
tclset("SphereAttrData(ZMax)", MyPropData.MyItem);
setProp();
Cet exemple montre comment gérer les données de propriété en utilisant la variable objet JavaScript "MyPropData". Les données de propriété peuvent être enregistrées et lues dans les fichiers de scène Ayam à l'aide d'une variable de tableau miroir du côté Tcl (également appelée "MyPropData"). Pour que cela fonctionne correctement, l'initialisation de l'objet JavaScript doit être limitée à la première exécution du script : lorsque les données de propriété ont été lues à partir d'un fichier de scène, l'initialisation ne doit pas être exécutée, mais les données lues doivent être récupérées dans le contexte Tcl. C'est l'objet de la première instruction "if", qui vérifie l'existence de la variable miroir du tableau Tcl, dans l'exemple ci-dessus.

En suivant ce schéma de duplication des structures de données du côté Tcl et JavaScript, on crée maintenant l'interface graphique de propriété, qui est également limitée à un seul script exécuté par une instruction "if" similaire.

Après l'interface graphique, un objet Sphère est créé et paramétré en fonction des données de l'interface graphique de propriété, qui est utilisée comme rayon, zmin et valeur zmax.

6.8 Interface de script Lua

Cette section contient la documentation de l'interface de scripting Lua qui est disponible après le chargement du plugin "luainterp".[∗]

Au chargement, le plugin "luainterp" crée un contexte Lua qui existe (avec toutes les variables et objets qui y sont définis) jusqu'à la sortie de Ayam.

Accéder à Lua à partir de Tcl et des objets script

La fonctionnalité Lua est accessible depuis l'interface de script Tcl via la commande "luaEval". La commande peut être utilisée soit pour exécuter directement le code Lua fourni via l'argument commands (code Tcl en gras) :

» luaEval {a = 0; a = a + 5.5; tclset("a", a);}
ou pour exécuter un code Lua à partir d'un fichier :
» luaEval -f scriptfile.lua
Notez que cette commande n'est pas disponible dans l'interprèteur sécurisé. En outre, les scripts objets peuvent également être implémentés en Lua, à condition que la première ligne du script soit un commentaire qui indique à Ayam d'utiliser l'interpréteur Lua :
-- Ayam, use: Lua
a = 0
...
Notez que le contexte de script Lua hérite des limitations du contexte Tcl appelant. Par exemple, lors de l'exécution d'un objet Script, le code suivant échoue :
tcleval("exit")
parce que la commande Tcl "exit" n'est pas disponible dans l'interpréteur sécurisé. La commande n'échouera pas, lorsque le contexte d'appel est l'interpréteur Tcl principal ; on peut par exemple taper dans la console Ayam :
» luaEval {tcleval("exit")}
and Ayam quits (Voir aussi la section: Interpréteur sécurisé).

Fonctions Lua

Cette sous-section informe sur les fonctions globales supplémentaires disponibles dans l'interprète Ayam Lua.

Il s'agit de commandes Tcl converties (par exemple : "crtOb()"), "tcleval()", "tclvar()", et "tclset()".

Commandes converties :
La fonctionnalité de Ayam est accessible depuis Lua via un ensemble plus large de fonctions globales, appelées commandes Tcl correspondantes. Par exemple, les objets Ayam peuvent être créés dans Lua en utilisant un appel de fonction comme celui-ci :

crtOb("NCircle")
or, with additional arguments:
crtOb("NCircle", "-radius", 3.0)
En général, toutes les commandes disponibles dans l'interpréteur sécurisé Ayam Tcl sont également disponibles sous forme de fonctions (voir la section Procédures and Commandes pour une liste plus ou moins complète de ces commandes).

Notez que les procédures Tcl ne sont généralement pas disponibles en tant que fonction Lua globale, mais elles peuvent être appelées en utilisant "tcleval()" comme indiqué dans le paragraphe suivant.

tcleval():
Cette fonction Lua permet d'évaluer des scripts Tcl quelconques, livrés sous forme de chaine comme argument :

a = 42
a = tcleval("puts " .. a .. "; return 5;")
tcleval("puts " .. a)
-- expected output: 42 5
La fonction "tcleval()" donne accès à toutes les fonctionnalités de Ayam qui sont juste disponibles en tant que procédure Tcl. Notez que les valeurs de retour sont correctement transférées à Lua selon les règles de conversion des données comme documenté ci-dessous. Cependant, en raison d'une conversion intermédiaire en chaîne , le surcoût d'un tel appel est considérable et le transport de données en masse doit être organisé par d'autres moyens, voir ci-dessous.

tclvar():
La fonction Lua "tclvar()" permet d'établir un lien entre une variable Tcl et une variable correspondante dans le contexte Lua. La fonction "tclvar()" crée une trace d'écriture sur la variable Tcl, de sorte que les changements du côté Tcl sont toujours automatiquement répercutés du côté Lua :

tclvar("a")
tcleval("set a 42")
tcleval("puts " .. a)
-- expected output: 42
Notez que la variable correspondante du côté Lua fait n'existe pas tant que la première opération d'écriture sur la variable Tcl ait lieu. La variable Tcl, à son tour, n'a pas besoin d'exister, lorsque la fonction "tclvar()" est appelée (c'est-à-dire que tout le travail est fait dans le rappel de trace). Si le nom de la variable contient un spécificateur d'espace de noms, cet espace de noms doit exister, lorsque la fonction "tclvar()" est appelée.

Bien qu'il semble parfaitement adapté, "tclvar()" ne peut pas être utilisé pour gérer un tableau de données de propriétés (si le tableau contient des composants à enregistrer dans des fichiers de scènes Ayam). En effet, à la lecture d'un fichier de scène contenant de tels éléments de tableau enregistrés, les éléments seront lus (et placés dans le contexte Tcl) avant que le script ne puisse établir la trace d'écriture à l'aide de "tclvar()" et les données du fichier de scène n'arriveront jamais dans le contexte Lua. Il n'y a pas de moyen facile de contourner ce problème. Une suggestion pour gérer un tableau de données de propriété est présentée dans la section d'exemples complets ci-dessous.

tclset():
La troisième fonction Lua globale est "tclset()" qui permet de définir efficacement les variables Tcl à partir du contexte Lua en évitant la conversion en données chaîne et inversement. Par exemple :

a = 3.3
b = {1, 3, 5}
tclset("a", a)
tclset("b", b)
fixe la variable Tcl "a" à la valeur en virgule flottante 3.3, et "b" à une liste de valeurs entières { 1 3 5 }.
Notez que les noms de variables peuvent également pointer vers des éléments de tableau Tcl, par exemple
tclset("SphereAttrData(Radius)", 1.2)
définit l'élément Radius dans le tableau SphereAttrData ; ou contient des spécificateurs d'espace de noms, par exemple
tclset("::MyNameSpace::Radius", 1.2)
définit la variable Radius dans l'espace de noms MyNameSpace.

Conversion des données

Lorsque les données sont transférées du côté Tcl vers le côté Lua (par exemple, lors de la conversion des valeurs de retour de "tcleval()" ou des valeurs de variables liées via "tclvar()"), les conversions suivantes sont en vigueur : Les types de données scalaires seront convertis en leurs équivalents directement correspondants. Les listes seront converties en tableaux (l'imbrication est autorisée et produira des tableaux imbriqués en conséquence). Les tableaux associatifs seront convertis en tableaux avec des clés correctement nommées. Les chaînes Unicode ne sont actuellement pas prises en charge. Voir également le tableau ci-dessous.

TclLua
Boolean (true, false)Boolean (true, false)
Integer (2)Integer (2)
Double (3.14)Double (3.14)
String ("mystr")String ("mystr")
List ({0 1 2})Array ({0, 1, 2})
Array (mya(mye) = 0.1)Table (mya.mye = 0.1)

Conversion des données de Tcl vers Lua

Lorsque des données sont transférées du côté Lua au côté Tcl (par exemple en tant qu'argument de fonction), les conversions suivantes sont en vigueur : Les types de données scalaires seront convertis en leurs équivalents directement correspondants, les tableaux seront convertis en listes (l'imbrication est autorisée et produira des listes imbriquées en conséquence). Les tableaux épars et mixtes ne sont actuellement pas pris en charge. Les chaînes de caractères Unicode ne sont pas non plus prises en charge actuellement. Voir aussi le tableau suivant.

LuaTcl
Boolean (true, false)Boolean (true, false)
Integer (2)Integer (2)
Double (3.14)Double (3.14)
String ("mystr")String ("mystr")
Array ({0, 1, 2})List ({0 1 2})

Conversion des données de Lua vers Tcl

Le transport/la conversion des entrées de tableau (en éléments de tableau associatif, par exemple) peut être organisé manuellement de cette manière :

a.b = 3.14
tclset("a(b)", a.b)

Exemples complets

Cette section contient deux exemples complets d'objets Script écrits en Lua.

Pour le premier exemple, utilisez le type d'objet Script "Modify" et mettez une sphère comme objet enfant de l'objet Script. 

-- Ayam, use: Lua
tclvar("SphereAttrData")
getProp()
if SphereAttrData then
  tclset("SphereAttrData(ZMin)", -SphereAttrData.Radius)
  tclset("SphereAttrData(ZMax)", SphereAttrData.Radius)
  setProp()
end
Le script ci-dessus permet de s'assurer que les paramètres ZMin et ZMax de l'objet Sphère correspondent toujours à son rayon. Tout d'abord, un lien est établi à partir du tableau de données des propriétés de l'objet Sphere original "SphereAttrData", de sorte que lorsque "getProp()" (une commande Tcl Ayam convertie) est appelé, l'objet Lua "SphereAttrData" est également rempli de données significatives.
La ligne suivante (le if) est une mesure de sécurité qui empêche l'échec du script si l'objet enfant de l'objet Script n'est pas un objet Sphere.
Maintenant, la valeur du rayon est retransférée à Tcl directement dans le tableau des données de propriété aux entrées ZMin et ZMax respectivement à l'aide de "tclset".
Enfin, la propriété modifiée est à nouveau transférée à l'objet Sphère avec une commande Tcl Ayam convertie "setProp()".

L'exemple suivant montre comment gérer une interface graphique de propriété dans un script objet Script implémenté par Lua. Utilisez le type d'objet Script "Create" et ajoutez une balise "NP MyProp" pour voir l'interface graphique des propriétés. 

-- Ayam, use: Lua, save array: MyPropData
if tcleval("info exists MyPropData;") == 0 then
  -- initial script run (but not when loaded from scene file!)
  MyPropData = {}
  MyPropData.MyItem = tcleval("set MyPropData(MyItem) 1.0;")
  tcleval("set MyPropData(SP) {MyItem};")
else
  -- all following script runs (and also when loaded from scene file!)
  MyPropData = {}
  MyPropData.MyItem = tcleval("set MyPropData(MyItem);")
end
if tcleval("info exists MyPropGUI;") == 0 then
  -- create property GUI "MyProp"
  tcleval("set ::phw [addPropertyGUI MyProp \"\" \"\"];")
  tcleval("addParam $::phw MyPropData MyItem;")
end
crtOb("Sphere")
sL()
getProp()
tclset("SphereAttrData(Radius)", MyPropData.MyItem)
tclset("SphereAttrData(ZMin)", -MyPropData.MyItem)
tclset("SphereAttrData(ZMax)", MyPropData.MyItem)
setProp()
Cet exemple montre comment gérer les données sur les propriétés à l'aide de la variable objet Lua "MyPropData". Les données de propriété peuvent être enregistrées et lues dans les fichiers de scène Ayam à l'aide d'une variable de tableau miroir du côté Tcl (également appelée "MyPropData"). Pour que cela fonctionne correctement, l'initialisation de l'objet Lua doit être limitée à la première exécution du script : lorsque les données de propriété ont été lues à partir d'un fichier de scène, l'initialisation ne doit pas être exécutée, mais les données lues doivent être récupérées dans le contexte Tcl. C'est l'objet de la première instruction "if", qui vérifie l'existence de la variable miroir du tableau Tcl, dans l'exemple ci-dessus.

En suivant ce schéma de doubles structures de données en miroir des côtés Tcl et Lua, on crée maintenant l'interface graphique de propriété, qui est également limitée à un seul script exécuté par une instruction "if" similaire.

Après l'interface graphique, un objet Sphère est créé et paramétré en fonction des données de l'interface graphique de propriété, qui est utilisée comme rayon, zmin et valeur zmax.

Page suivante Page précédente Table des matières