Le processus de programmation visuelle peut être une activité créative puissante, mais le flux du programme et les entrées utilisateur clés peuvent très rapidement être occultés par la complexité et/ou la disposition de l'espace de travail. Voici quelques bonnes pratiques pour gérer votre programme.

Alignement

Une fois que vous avez ajouté plusieurs nœuds à l’espace de travail, vous pouvez réorganiser la disposition des nœuds pour plus de clarté. Lorsque vous sélectionnez plusieurs nœuds et cliquez avec le bouton droit de la souris sur l’espace de travail, la fenêtre contextuelle inclut un menu Aligner la sélection avec les options de justification et de distribution dans X et Y.

1. Sélectionnez plusieurs nœuds.

2. Cliquez avec le bouton droit de la souris sur l’espace de travail.

3. Utilisez les options de Aligner la sélection.

Notes

Avec une certaine expérience, vous pourrez probablement "lire" le programme visuel en examinant les noms des nœuds et en suivant le flux du programme. Pour les utilisateurs de tous niveaux, il est également recommandé d’inclure des libellés et des descriptions en texte simple. Pour ce faire, Dynamo possède un nœud Notes avec un champ de texte modifiable. Vous pouvez ajouter des notes à l’espace de travail de deux manières :

1. Accédez au menu Modifier > Créer une note.

2. Utiliser le raccourci clavier Ctrl+W.

Une fois la note ajoutée à l'espace de travail, un champ de texte s'affiche pour vous permettre de modifier le texte de la note. Une fois la note créée, vous pouvez la modifier en double-cliquant sur le nœud Note ou en cliquant dessus avec le bouton droit de la souris.

Groupement

Lorsque votre programme visuel est grand, il est utile d’identifier les étapes plus importantes qui seront exécutées. Vous pouvez mettre en surbrillance des ensembles de nœuds plus grands avec un groupe pour les libeller avec un rectangle de couleur en arrière-plan et un titre. Il existe trois méthodes pour créer un groupe avec plus d’un nœud sélectionné :

1. Accédez au menu Modifier > Créer un groupe.

2. Utilisez le raccourci clavier Ctrl+G.

3. Cliquez avec le bouton droit de la souris sur l'espace de travail et choisissez Créer un groupe.

Une fois le groupe créé, vous pouvez modifier ses paramètres, tels que son titre et sa couleur.

Voici un exemple de programme à partir duquel les notes et les groupes ont été ajoutés :

1. Note : « Paramètres de grille »

2. Note : "Points de la grille"

3. Groupe : "Créer une grille de points"

4. Groupe : "Créer un point d'attraction"

5. Note : "Calibrer les valeurs de distance"

6. Note : "Grille variable de cercles"

Cette page de référence présente les meilleures pratiques décrites dans la section Stratégies de script, avec plus de détails sur les bibliothèques de codes, l'étiquetage et le style. Vous allez utiliser Python pour illustrer les concepts ci-dessous. Les mêmes principes s'appliquent à Python et C# (Zerotouch), mais la syntaxe est différente.

Bibliothèques à utiliser

Les bibliothèques standard sont externes à Dynamo et sont présentes dans les langages de programmation Python et C# (Zerotouch). Dynamo possède également son propre ensemble de bibliothèques qui correspondent directement à sa hiérarchie de nœuds, permettant à l'utilisateur de coder tout ce qui peut être fait avec des nœuds et des fils. Voici un guide qui présente le contenu auquel chaque bibliothèque Dynamo permet d’accéder et qui explique quand utiliser une bibliothèque standard.

Bibliothèques standard et bibliothèques Dynamo

• Les bibliothèques standard de Python et C# peuvent être utilisées pour créer des données avancées et des structures de flux dans l’environnement Dynamo.

• Les bibliothèques Dynamo correspondent directement à la hiérarchie des nœuds pour la création de géométries et d’autres objets Dynamo.

Bibliothèques Dynamo

1. ProtoGeometry*

   • Fonctionnalités : Arc, Zone de contour, Cercle, Cône, Système de coordonnées, Cuboïde, Courbe, Cylindre, Arête, Ellipse, Arc d’ellipse, Face, Géométrie, Hélice, Groupe d’index, Ligne, Maillage, Courbe NURBS, Surface NURBS, Plan, Point, Polygone, Rectangle, Solide, Sphère, Surface, Topologie, T-Spline, UV, Vecteur, Sommet.

   • Comment importer : import Autodesk.DesignScript.Geometry

   ``

2. DSCoreNodes

   • Fonctionnalités : Couleur, Intervalle de couleurs 2D, Date et heure, Durée, E/S, Formule, Logique, Liste, Math, Arbre quadratique, Chaîne, Thread.

   • Comment importer : import DSCore

3. Tessellation

   • Fonctionnalités : Coque convexe, Delaunay, Voronoi.

   • Comment importer : import Tessellation

4. DSOffice

   • Fonctionnalité : Excel.

   • Comment importer : import DSOffice

Étiquetage soigneux

Lors de la création du script, vous utilisez en permanence des identificateurs pour indiquer des éléments tels que des variables, des types, des fonctions et d'autres entités. Grâce à ce système de notation symbolique, et à la création d'algorithmes, vous pouvez facilement vous référer à des informations par le biais de libellés, généralement composés d'une séquence de caractères. Le fait de nommer les choses correctement joue un rôle important dans l'écriture de code pour que ce dernier soit facilement lu et compris par d'autres personnes, ainsi que par vous-même dans le futur ! Voici quelques conseils à retenir lorsque vous nommez des éléments dans votre script :

Il est correct d’utiliser des abréviations, mais il convient d’expliquer l’abréviation par un commentaire :

### BAD
csfX = 1.6
csfY= 1.3
csfZ = 1.0

### GOOD
# column scale factor (csf)
csfX = 1.6
csfY= 1.3
csfZ = 1.0

Évitez les libellés redondants :

### BAD
import car
seat = car.CarSeat()
tire = car.CarTire()

### GOOD
import car
seat = car.Seat()
tire = car.Tire()

Utilisez une logique positive pour les noms de variables au lieu d’une logique négative :

### BAD
if 'mystring' not in text:
    print 'not found'
else:
    print 'found'
    print 'processing'

### GOOD
if 'mystring' in text:
    print 'found'
    print 'processing'
else:
    print 'not found'

Préférez la « notation inverse » :

### BAD
agents = …
active_agents = …
dead_agents ...

### GOOD
agents = …
agents_active = …
agents_dead = ...

Il est plus logique d’utiliser des termes structurels.

Les alias doivent être utilisés pour raccourcir les chaînes trop longues et souvent répétées :

### BAD
from RevitServices.Persistence import DocumentManager

DocumentManager = DM

doc = DM.Instance.CurrentDBDocument
uiapp = DM.Instance.CurrentUIApplication

### GOOD
from RevitServices.Persistence import DocumentManager as DM

doc = DM.Instance.CurrentDBDocument
uiapp = DM.Instance.CurrentUIApplication

L’utilisation d’alias peut rapidement conduire à des programmes déroutants et non standard.

Utilisez uniquement les mots nécessaires :

### BAD
rotateToCoord = rotateFromCoord.Rotate(solid.ContextCoordinateSystem.Origin,Vector.ByCoordinates(0,0,1),5)

### GOOD
toCoord = fromCoord.Rotate(solid.ContextCoordinateSystem.Origin,Vector.ByCoordinates(0,0,1),5)

« Rendez les choses aussi simples que possible, mais pas plus simples. » – Albert Einstein

Style cohérent

En règle générale, il existe plusieurs méthodes pour programmer à peu près tout ce que l'on veut. Votre "style personnel" de script est donc le résultat des innombrables petites décisions que vous choisissez de prendre (ou de ne pas prendre). Cela dit, la lisibilité et la pérennité de votre code sont le résultat direct de sa cohérence interne et de sa conformité aux conventions stylistiques générales. En règle générale, des lignes de code qui se ressemblent à deux emplacements différents doivent également fonctionner de la même manière. Voici quelques conseils pour écrire du code clair et cohérent.

Conventions d’appellation : (choisissez l’une des conventions ci-dessous pour chaque type d’entité de votre code et associez-la à votre système.)

• Variables, fonctions, méthodes, packages, modules : lower_case_with_underscores

• Classes et exceptions : CapWords

• Méthodes protégées et fonctions internes : _single_leading_underscore(self, ...)

• Méthodes privées : __double_leading_underscore(self, ...)

• Des constantes : ALL_CAPS_WITH_UNDERSCORES

Conseil : évitez les variables d’une lettre (p. ex. l, O, I) sauf dans des blocs très courts, quand la signification est clairement visible dans le contexte immédiat.

Utilisation de lignes vierges :

• Entourez les définitions de classe et de fonction de niveau supérieur de deux lignes vierges.

  • Les définitions de méthode à l'intérieur d'une classe sont entourées d'une seule ligne vierge.

  • Des lignes vierges supplémentaires peuvent être utilisées (occasionnellement) pour séparer des groupes de fonctions associées.

Évitez les espaces superflus :

• Immédiatement entre des parenthèses, des crochets ou des accolades :

  Copy

  ### BAD
  function( apples[ 1 ], { oranges: 2 } )

  Copy

  ### GOOD:
  function(apples[1], {oranges: 2})

• Immédiatement avant une virgule, un point-virgule ou un signe deux-points :

  Copy

  ### BAD
   if x == 2 : print x , y ; x , y = y , x

  Copy

  ### GOOD
    if x == 2: print x, y; x, y = y, x

• Immédiatement avant la parenthèse ouvrante qui lance la liste d'arguments d'un appel de fonction :

  Copy

  ### BAD
  function (1)

  Copy

  ### GOOD
  function(1)

• Immédiatement avant la parenthèse ouverte qui démarre l'indexation ou l'extraction :

  Copy

  ### BAD
  dict ['key'] = list [index]

  Copy

  ### GOOD
  dict['key'] = list[index]

• Entourez toujours ces opérateurs binaires d’un seul espace de part et d’autre :

  Copy

  assignment ( = )
  augmented assignment ( += , -= etc.)
  comparisons ( == , < , > , != , <> , <= , >= , in , not in , is , is not )
  Booleans ( and , or , not )

Faites attention à la longueur des lignes :

• Ne dépassez pas les 79 caractères.

• Limiter la largeur de la fenêtre de l'éditeur requise permet d'ouvrir plusieurs fichiers côte à côte et facilite l'utilisation d'outils de révision de code qui présentent les deux versions dans des colonnes adjacentes.

• Vous pouvez couper les longues lignes sur plusieurs lignes en mettant les expressions entre parenthèses :

Évitez les commentaires évidents et redondants :

• Parfois, réduire le nombre de commentaires permet de rendre le code plus lisible, notamment si cela vous oblige à utiliser des noms de symboles significatifs à la place.

• L'adoption de bonnes habitudes de codage réduit la dépendance aux commentaires :

  Copy

  ### BAD
    # get the country code
    country_code = get_country_code(address)
  
    # if country code is US
    if (country_code == 'US'):
      # display the form input for state
      print form_input_state()

  Copy

  ### GOOD
    # display state selection for US users
    country_code = get_country_code(address)
    if (country_code == 'US'):
      print form_input_state()

Conseil : les commentaires vous expliquent pourquoi, le code vous explique comment.

Examinez attentivement le code source ouvert :

• Les projets Open Source reposent sur les efforts de collaboration de nombreux développeurs. Ces projets doivent garantir un niveau élevé de lisibilité du code afin que l'équipe puisse travailler ensemble le plus efficacement possible. Par conséquent, il est recommandé de parcourir le code source de ces projets pour observer ce que font ces développeurs.

• Améliorez vos conventions :

  • Demandez-vous si chaque convention fonctionne ou non pour les besoins définis.

  • Les fonctionnalités et l'efficacité sont-elles compromises ?

Normes C# (Zerotouch)

Consultez ces pages wiki pour obtenir des conseils sur l’écriture de C# pour Zerotouch et la participation à Dynamo :

• Cette page wiki traite de certaines normes générales de codage pour la documentation et le test de votre code : https://github.com/DynamoDS/Dynamo/wiki/Coding-Standards

• Cette page wiki traite spécifiquement des normes d’attribution de noms pour les bibliothèques, les catégories, les noms de nœuds, les noms de ports et les abréviations : https://github.com/DynamoDS/Dynamo/wiki/Coding-Standards

Objets non gérés :

Lorsque vous utilisez la bibliothèque de géométrie de Dynamo (ProtoGeometry) à partir de Python ou de C#, les objets de géométrie créés ne sont pas gérés par la machine virtuelle, et la mémoire d’un grand nombre de ces objets doit être nettoyée manuellement. Pour nettoyer des objets natifs ou non gérés, vous pouvez utiliser la méthode Dispose ou le mot-clé using. Consultez cette entrée Wiki pour obtenir un aperçu : https://github.com/DynamoDS/Dynamo/wiki/Zero-Touch-Plugin-Development#dispose—using-statement.

Il vous suffit de supprimer les ressources non gérées que vous ne renvoyez pas dans le graphique ou pour lesquelles vous n’enregistrez pas de référence. Le reste de cette section fait référence à ces objets comme étant une géométrie intermédiaire. Vous pouvez voir un exemple de cette classe d’objets dans l’exemple de code ci-dessous. La fonction C# Zero Touch singleCube renvoie un seul cube, mais permet de créer 10000 cubes supplémentaires au cours de son exécution. Il est possible que cette autre géométrie ait été utilisée comme géométrie de construction intermédiaire.

Cette fonction Zero Touch risque de bloquer Dynamo , étant donné que vous avez créé 10000 solides, mais n’avez enregistré qu’un seul d’entre eux et n’avez renvoyé que celui-ci. Vous devez plutôt éliminer tous les cubes intermédiaires, sauf celui renvoyé. Il est préférable de ne pas supprimer les objets renvoyés, car ces derniers sont propagés dans le graphique et utilisés par d'autres nœuds.

public Cuboid singleCube(){

  var output = Cuboid.ByLengths(1,1,1);

  for(int i = 0; i<10000;i++){
    output = Cuboid.ByLengths(1,1,1);
  }
  return output;
}

Le code réparé doit ressembler à ceci :

 public Cuboid singleCube(){

   var output = Cuboid.ByLengths(1,1,1);
   var toDispose = new List<Geometry>();

   for(int i = 0; i<10000;i++){
     toDispose.Add(Cuboid.ByLengths(1,1,1));
   }

   foreach(IDisposable item in toDispose ){
     item.Dispose();
   }

   return output;
 }

En général, il suffit de supprimer la géométrie comme Surfaces, Curves et Solids. Pour plus de sécurité, vous pouvez supprimer tous les types de géométrie (Vectors, Points, CoordinateSystems).

Cette partie du guide compile des pratiques recommandées. Elle met en lumière plusieurs stratégies qui se sont avérées, via l'expérience et la recherche, les plus propices à des workflows paramétriques de qualité. En tant que concepteurs et programmeurs, notre indicateur de qualité est principalement axé sur la pérennité, la fiabilité, la facilité d'utilisation et l'efficacité de nos outils. Bien que ces pratiques recommandées soient associées à des exemples spécifiques pour les scripts visuels ou textuels, les principes s’appliquent à tous les environnements de programmation et peuvent alimenter de nombreux workflows de calcul.

Avant ce chapitre, le guide a présenté les étapes à suivre pour mettre en œuvre les puissantes fonctionnalités de script visuel de Dynamo. Une bonne compréhension de ces fonctionnalités est une base solide et la première étape dans la construction de programmes visuels fiables. Lorsque vous utilisez vos programmes visuels sur le terrain, partagez-les avec vos collègues, corrigez les erreurs ou testez les limites avec lesquelles vous rencontrez d'autres problèmes. Si une autre personne va utiliser votre programme ou si vous souhaitez l'ouvrir dans six mois, il doit être clair d'un point de vue graphique et logique dès l'ouverture. Dynamo dispose de nombreux outils pour gérer la complexité de votre programme. Ce chapitre vous expliquera les conditions d’utilisation de ces derniers.

Simplification des processus

Lorsque vous développez votre graphique Dynamo et testez vos idées, la taille et la complexité de ce dernier peuvent rapidement augmenter. Bien qu’il soit important de créer un programme fonctionnel, il est tout aussi crucial de le faire le plus simplement possible. Non seulement votre graphique s'exécutera plus rapidement et de manière plus prévisible, mais vous comprendrez sa logique ultérieurement. Les méthodes suivantes vous aideront à clarifier la logique de votre graphique.

Modularisation avec les groupes

• Les groupes vous permettent de créer des pièces fonctionnellement distinctes lorsque vous construisez un programme

• Les groupes vous permettent de déplacer de grandes parties du programme tout en maintenant la modularité et l’alignement

• Vous pouvez modifier la couleur du groupe pour différencier ce que font les groupes (entrées et fonctions)

• Vous pouvez utiliser des groupes pour commencer à organiser votre graphique afin de simplifier la création de nœuds personnalisés

Les couleurs de ce programme identifient l’objectif de chaque groupe. Cette stratégie sert à créer une hiérarchie dans les normes graphiques ou les gabarits que vous développez.

1. Groupe de fonctions (bleu)

2. Groupe d'entrées (orange)

3. Groupe de scripts (vert)

Développement efficace avec les blocs de code

• Vous pouvez parfois utiliser un bloc de code pour saisir un nombre ou une méthode de nœud plus rapidement qu’en effectuant une recherche (Point.ByCoordinates, Number, String, Formula)

• Les blocs de code sont utiles lorsque vous souhaitez définir des fonctions personnalisées dans DesignScript afin de réduire le nombre de nœuds dans un graphique

Les deux encadrés exécutent la même fonction. Il était beaucoup plus rapide d'écrire quelques lignes de code que de rechercher et d'ajouter chaque nœud individuellement. Le bloc de code est également beaucoup plus concis.

1. Script de conception écrit en bloc de code

2. Programme équivalent en nœuds

Condenser grâce à Nœud vers code

• Vous pouvez réduire la complexité d’un graphique en utilisant la fonctionnalité Nœud vers code : elle permet de sélectionner un ensemble de nœuds simples et d’en écrire le DesignScript correspondant dans un bloc de code unique

• La fonctionnalité Nœud vers code permet de** condenser du code sans nuire à la clarté du programme**

• Voici les avantages de l’utilisation de Nœud vers code :

  • Condense facilement du code en un composant qui reste modifiable

  • Peut simplifier une partie significative du graphique

  • Utile si le mini-programme ne sera pas souvent modifié

  • Utile pour intégrer d’autres fonctionnalités de bloc de code, telles que des fonctions

• Voici les inconvénients de l’utilisation de Nœud vers code :

  • L’attribution de noms génériques réduit la lisibilité

  • Plus difficile à comprendre pour les autres utilisateurs

  • Aucun moyen simple de revenir à la version de programmation visuelle

1. Programme existant

2. Bloc de code créé à partir de Nœud vers code

Accès aux données en toute flexibilité grâce à List@Level

• L’utilisation de List@Level vous permet de réduire la complexité de votre graphique en remplaçant les nœuds List.Map et List.Combine qui peuvent occuper une grande partie de la zone de dessin

• List@Level fournit une méthode plus** rapide que List.Map/List.Combine pour établir la logique de nœud** en vous permettant d’accéder aux données à n’importe quel niveau d’une liste, directement à partir du port d’entrée d’un nœud

Vous pouvez vérifier le nombre de valeurs True renvoyées par BoundingBox.Contains et dans quelles listes ces valeurs sont renvoyées en activant List@Level pour l’entrée « list » de CountTrue. La fonction List@Level permet à l'utilisateur de déterminer à quel niveau l'entrée va extraire des données. La fonction List@Level est flexible, efficace et vivement recommandée par rapport à d'autres méthodes impliquant List.Map et List.Combine.

1. Comptage des valeurs True au niveau de la liste 2

2. Comptage des valeurs True au niveau de la liste 3

Maintenir la lisibilité

En plus de rendre le graphique aussi simple et efficace que possible, essayez d'améliorer la clarté graphique. Malgré vos efforts pour rendre votre graphique intuitif grâce à des regroupements logiques, les relations risquent de ne pas être évidentes. L'insertion d'une note simple dans un groupe ou l'attribution de nouveaux noms aux curseurs permet aux utilisateurs d'éviter tout malentendu ou mouvement panoramique inutile sur le graphique. Les méthodes suivantes vous aideront à appliquer la cohérence graphique dans vos graphiques.

Continuité visuelle grâce à l’alignement des nœuds

• Pour réduire votre charge de travail après avoir créé votre graphique, assurez-vous que la disposition des nœuds est lisible en alignant les nœuds régulièrement et au fur et à mesure de votre travail

• Si d’autres utilisateurs vont travailler avec votre graphique, assurez-vous que la disposition des liaisons de nœud s’enchaîne facilement avant la livraison

• Pour vous aider avec la tâche d’alignement, utilisez la fonction « Arranger l’affichage des nœuds » pour aligner automatiquement votre graphique, même si elle est moins précise que vous-même

1. Graphique non organisé

2. Graphique aligné

Étiquetage descriptif par changement de nom

• L’attribution de nouveaux noms aux entrées permet aux autres utilisateurs de comprendre facilement votre graphique, notamment si ce qu’ils connectent n’est pas affiché à l’écran

• Veillez à renommer les nœuds en plus des entrées. Une autre solution consiste à créer un nœud personnalisé à partir d’un cluster de nœuds et à le renommer. Il sera alors évident qu’il contient autre chose

1. Entrées pour la manipulation de surfaces

2. Entrées pour les paramètres architecturaux

3. Entrées du script de simulation de drainage

Pour renommer un nœud, cliquez avec le bouton droit de la souris sur son nom et sélectionnez « Renommer le nœud… ».

Explication avec des notes

• Vous devez ajouter une note si quelque chose dans le graphique requiert une explication en langage simple que les nœuds ne peuvent pas exprimer

• Vous devez ajouter une note si un ensemble de nœuds ou de groupes est trop volumineux ou trop complexe et ne peut pas être facilement compris immédiatement

1. Note décrivant la partie du programme qui renvoie les distances de conversion brutes

2. Note décrivant le code qui mappe ces valeurs avec une onde sinusoïdale

Flexibilité continue

Surveiller les données avec les bulles Watch et d’aperçu

• Utilisez les bulles Watch et d’aperçu lorsque vous créez le programme pour** vérifier que les sorties clés renvoient le résultat attendu**

Les nœuds Watch sont utilisés pour comparer :

1. Distances de conversion brutes

2. Valeurs transmises par l’équation sinusoïdale

Garantir la réutilisation

Il est fort probable qu'une autre personne ouvre votre programme à un moment donné, même si vous travaillez indépendamment. Cette personne doit pouvoir comprendre rapidement ce dont le programme a besoin et ce qu'il produit à partir de ses entrées et sorties. Cela est particulièrement important lorsque vous développez un nœud personnalisé à partager avec la communauté Dynamo et à utiliser dans le programme d'un autre utilisateur. Ces pratiques permettent de construire des programmes et des nœuds robustes et réutilisables.

Gérer les E/S

• Pour garantir la lisibilité et l’évolutivité, essayez de réduire les entrées et les sorties autant que possible

• Essayez de déterminer la méthode de création de la logique en créant d’abord une ébauche de la manière dont la logique peut fonctionner avant d’ajouter un nœud à la zone de dessin. Lorsque vous développez la première ébauche, effectuez un suivi des entrées et des sorties qui seront converties en scripts

Utiliser les valeurs prédéfinies pour incorporer les valeurs d’entrée

• Si vous souhaitez intégrer des options ou conditions particulières au graphique, utilisez les valeurs prédéfinies pour y accéder rapidement

• Vous pouvez également utiliser les valeurs prédéfinies pour réduire la complexité en mettant en cache des valeurs de curseur spécifiques dans un graphique avec des temps d’exécution longs

Limiter les programmes grâce aux nœuds personnalisés

• Vous devez utiliser un nœud personnalisé si votre programme peut être regroupé dans un seul conteneur

• Vous devez utiliser un nœud personnalisé lorsqu’une partie du graphique sera réutilisée souvent dans d’autres programmes

• Vous devez utiliser un nœud personnalisé pour partager une fonctionnalité avec la communauté Dynamo

La collecte du programme de conversion de points dans un nœud personnalisé permet de simplifier et de rendre transférable un programme robuste et unique. Les ports d'entrée bien nommés aideront d'autres utilisateurs à comprendre comment utiliser le nœud. N'oubliez pas d'ajouter des descriptions et des types de données requis pour chaque entrée.

1. Programme d'attraction existant

2. Nœud personnalisé qui collecte ce programme, PointGrid

Créer des gabarits

• Vous pouvez créer des gabarits pour établir des normes graphiques dans vos graphiques visuels afin de vous assurer que les collaborateurs comprennent le graphique de manière standardisée

• Lors de la création d’un gabarit, vous pouvez normaliser les tailles de police et les couleurs de groupe afin de classer les types de workflow ou d’actions de données.

• Lors de la création d’un gabarit, vous pouvez même normaliser la façon dont vous souhaitez étiqueter, colorer ou styliser la différence entre les workflows front-end et back-end dans votre graphique.

1. L’interface utilisateur, ou la partie frontale, du programme inclut un nom de projet, des curseurs d’entrée et une géométrie d’importation.

2. La partie back-end du programme.

3. Regroupez les catégories de couleurs (conception générale, entrées, scripts Python, géométrie importée).

Exercice - Toit architectural

Téléchargez le fichier d’exemple en cliquant sur le lien ci-dessous.

Vous trouverez la liste complète des fichiers d'exemple dans l'annexe.

Maintenant que vous avez établi plusieurs meilleures pratiques, appliquez-les à un programme qui a été mis en place rapidement. Bien que le programme réussisse à générer le toit, l'état du graphique reflète le cheminement de pensée de l'auteur, à la manière d'une carte mentale. Il n'y a aucune organisation ou description de son utilisation. Vous allez parcourir les meilleures pratiques pour organiser, décrire et analyser le programme afin que d’autres utilisateurs puissent comprendre comment l’utiliser.

Le programme fonctionne, mais le graphique est désorganisé.

Commençons par déterminer les données et la géométrie renvoyées par le programme.

Comprendre quand des modifications importantes des données se produisent est crucial pour établir des divisions logiques, ou des modularités. Inspectez le reste du programme avec les nœuds Watch pour voir si vous pouvez déterminer les groupes avant de passer à l’étape suivante.

1. Ce nœud Code Block avec une équation mathématique semble être un élément crucial du programme. Un nœud Watch indique qu’il renvoie des listes de distances de conversion.

2. L’objectif de cette zone n’est pas évident. La disposition des valeurs True au niveau de la liste L2 de BoundingBox.Contains et la présence de List.FilterByBoolMask suggèrent que vous échantillonnez une partie de la grille de points.

Une fois que vous avez identifié les composantes essentielles du programme, placez-les dans des groupes.

Les groupes permettent à l’utilisateur de différencier visuellement les parties du programme.

1. Importer un modèle de site 3D

2. Convertir la grille de points en fonction de l'équation sinusoïdale

3. Exemple de portion de grille de points

4. Créer une surface de toit architecturale

5. Créer un mur-rideau en verre

Lorsque les groupes sont établis, alignez les nœuds pour créer une continuité visuelle sur le graphique.

La continuité visuelle aide l’utilisateur à voir le flux du programme et les relations implicites entre les nœuds.

Rendez le programme plus accessible en ajoutant un autre calque d'améliorations graphiques. Ajoutez des notes pour décrire le fonctionnement d’une zone spécifique du programme, donnez des noms personnalisés aux entrées et affectez des couleurs à différents types de groupes.

Ces améliorations graphiques permettent à l’utilisateur de mieux connaître les activités du programme. Les différentes couleurs de groupe permettent de distinguer les entrées des fonctions.

1. Notes

2. Entrées avec des noms descriptifs

Avant de commencer à condenser le programme, identifions un emplacement stratégique pour présenter le simulateur de drainage du script Python. Branchez la sortie de la première surface de toit mise à l’échelle dans l’entrée de script correspondante.

Vous avez choisi d’intégrer les scripts à ce stade du programme afin que la simulation de drainage puisse être exécutée sur la surface de toit unique d’origine. Cette surface spécifique n'est pas affichée en aperçu, mais elle vous évite d'avoir à choisir la surface supérieure de la polysurface chanfreinée.

1. Géométrie source pour l'entrée du script

2. Nœud Python

3. Curseurs d'entrée

4. "Commutateur" activé/désactivé

Maintenant que tout est en place, simplifions le graphique.

La condensation du programme grâce à Nœud vers code et à Nœud personnalisé a permis de réduire considérablement la taille du graphique. Les groupes qui créent la surface du toit et les murs ont été convertis en code, car ils sont très spécifiques de ce programme. Le groupe de conversion de points est contenu dans un nœud personnalisé, car il peut être utilisé dans un autre programme. Dans le fichier d'exemple, créez votre propre nœud personnalisé à partir du groupe Convertir les points.

1. Nœud personnalisé contenant le groupe "Convertir la grille de points"

2. Nœud vers code permettant de condenser les groupes "Créer une surface de toit architecturale et un mur-rideau"

Pour finir, créez des valeurs prédéfinies pour des formes de toit représentatives.

Ces entrées sont les principaux pilotes de la forme du toit et permettent aux utilisateurs de découvrir le potentiel du programme.

Votre programme avec des vues de deux valeurs prédéfinies.

Les motifs de drainage du toit permettent à l’utilisateur d’obtenir une vue analytique des valeurs prédéfinies respectives.

L'utilisation de scripts basés sur du texte dans l'environnement de script visuel permet d'établir des relations visuelles efficaces à l'aide de DesignScript, Python et ZeroTouch (C#). L'utilisateur peut exposer des éléments tels que des curseurs d'entrée, condenser des opérations importantes dans DesignScript et accéder à de puissants outils et bibliothèques via Python ou C#, le tout dans le même espace de travail. Si elle est gérée efficacement, la combinaison de ces stratégies peut améliorer significativement la personnalisation, la clarté et l'efficacité du programme global. Les instructions suivantes vous aideront à enrichir votre script visuel avec un script de texte.

Quand écrire un script ?

Les scripts de texte peuvent établir des relations plus complexes que la programmation visuelle, même si certaines de leurs fonctionnalités sont assez comparables. Cela est logique car les nœuds correspondent effectivement à du code pré-intégré, et nous pourrions probablement écrire un programme Dynamo dans DesignScript ou Python. Toutefois, nous utilisons les scripts visuels, car l'interface des nœuds et des fils crée un flux intuitif d'informations graphiques. Le fait de savoir quand les fonctionnalités du script de texte dépassent celles du script visuel vous permettra de déterminer lorsque ce script doit être utilisé sans renoncer à la nature intuitive des nœuds et des fils. Les instructions suivantes indiquent quand écrire des scripts et le langage à utiliser.

Utilisez les scripts de texte aux fins suivantes :

• Création de boucle

• Récursion

• Accès aux bibliothèques externes

Choisissez une langue :

Penser de manière paramétrique

Lorsque vous créez des scripts dans Dynamo, un environnement inévitablement paramétrique, il est judicieux de structurer votre code par rapport à la structure des nœuds et des fils dans lesquels il se trouvera. Considérez le nœud contenant votre script de texte comme s'il s'agissait d'un autre nœud du programme avec quelques entrées spécifiques, une fonction et une sortie attendue. Cela donne immédiatement à votre code à l'intérieur du nœud un petit jeu de variables à partir duquel travailler. C'est la clé d'un système paramétrique propre. Voici quelques conseils pour une meilleure intégration du code dans un programme visuel.

Identifiez les variables externes :

• Essayez de déterminer les paramètres donnés dans votre problème de conception afin de pouvoir développer un modèle qui se construit directement à partir de ces données.

• Avant d'écrire du code, identifiez les variables suivantes :

  • Un jeu minimal d'entrées

  • La sortie prévue

  • Des constantes

Plusieurs variables ont été établies avant l’écriture du code.

1. La surface sur laquelle nous allons simuler l'eau de pluie.

2. Le nombre de gouttes de pluie (agents) que nous voulons.

3. La distance que nous voulons que les gouttes de pluie parcourent.

4. Le basculement entre descendre le parcours le plus raide ou traverser la surface.

5. Le nœud Python avec le nombre d'entrées correspondant.

6. Un bloc de code rendant les courbes renvoyées bleues.

Concevez les relations internes :

• Le paramétrisme permet de modifier certains paramètres ou variables afin de manipuler ou de modifier le résultat final d’une équation ou d’un système.

• Lorsque des entités de votre script sont liées de façon logique, définissez-les comme des fonctions les unes des autres. De cette façon, si l'une d'entre elle est modifiée, l'autre peut être mise à jour proportionnellement.

• Réduisez le nombre d'entrées en exposant uniquement les paramètres clés :

  • Si un jeu de paramètres peut provenir de plusieurs paramètres parent, affichez uniquement les paramètres parent sous forme d'entrées de script. Cela permet d’accroître la facilité d’utilisation de votre script tout en réduisant la complexité de son interface.

« Modules » de code issus de l’exemple dans Nœud Python.

1. Entrées.

2. Variables internes au script.

3. Boucle qui utilise ces entrées et variables pour exécuter sa fonction.

Ne vous répétez pas (principe DRY) :

• Lorsque vous disposez de plusieurs méthodes pour exprimer la même chose dans votre script, les représentations dupliquées ne sont pas synchronisées parfois, ce qui peut entraîner des problèmes de maintenance, des mauvaises factorisations et des contradictions internes.

• Le principe du DRY est le suivant : "Chaque connaissance doit avoir une représentation unique, non ambiguë et autorisée au sein d'un système" :

  • Lorsque ce principe est appliqué correctement, tous les éléments associés de votre script changent de manière prévisible et uniforme, et tous les éléments non liés n’ont pas de conséquences logiques les uns sur les autres.

### BAD
for i in range(4):
  for j in range(4):
    point = Point.ByCoordinates(3*i, 3*j, 0)
    points.append(point)

### GOOD
count = IN[0]
pDist = IN[1]

for i in range(count):
  for j in range(count):
    point = Point.ByCoordinates(pDist*i, pDist*j, 0)
    points.append(point)

Structurer de manière modulaire

Lorsque votre code devient de plus long et plus complexe, l'idée principale ou l'algorithme global devient de plus en plus illisible. Il est également plus difficile d'en suivre le cours, de trouver des bogues quand des problèmes surviennent, d'intégrer d'autres lignes de code et d'assigner des tâches de développement. Pour éviter ces problèmes, il est judicieux d'écrire du code dans les modules. Il s'agit d'une stratégie d'organisation qui décompose le code en fonction de la tâche qu'elle exécute. Voici quelques conseils pour rendre vos scripts plus gérables par le biais de la modularisation.

Écrivez du code dans des modules :

• Un "module" est un groupe de lignes de code qui effectue une tâche spécifique et qui est semblable à un nœud Dynamo dans l’espace de travail.

• Il peut s'agir de tout ce qui doit être visuellement séparé du code adjacent (une fonction, une classe, un groupe d'entrées ou les bibliothèques que vous importez).

• Le développement de code dans des modules exploite la qualité visuelle intuitive des nœuds, ainsi que les relations complexes que seuls les scripts de texte peuvent atteindre.

Ces boucles appellent une classe nommée « agent » que nous allons développer dans l’exercice.

1. Module de code qui définit le point de départ de chaque agent.

2. Module de code qui met à jour l'agent.

3. Module de code qui trace une trajectoire pour le parcours de l’agent.

Détectez le code réutilisé :

• Si vous constatez que votre code produit un résultat identique (ou très similaire) à plusieurs endroits, trouvez des moyens de le regrouper dans une fonction qui peut être appelée.

• Les fonctions "Gestionnaire" contrôlent le flux de programmes et contiennent principalement des appels aux fonctions "Exécutant" qui gèrent les détails de bas niveau, comme le déplacement de données entre les structures.

Dans cet exemple, des sphères sont créées avec des rayons et des couleurs basés sur la valeur Z des points centraux.

1. Deux fonctions parent « Exécutant » : une fonction qui crée des sphères avec des rayons et des couleurs d’affichage en fonction de la valeur Z du point central.

2. Une fonction parent "Gestionnaire" qui combine les deux fonctions "Executant". L’appel de cette fonction appellera les deux fonctions qu’elle contient.

Montrez uniquement ce qui doit être vu :

• Une interface de module représente les éléments fournis et requis par le module.

• Une fois les interfaces entre les unités définies, la conception détaillée de chaque unité peut être effectuée séparément.

Séparabilité/Remplacement :

• Les modules n’ont pas de lien entre eux.

Formes générales de modularisation :

• Regroupement des lignes de code :

  Copy

  # IMPORT LIBRARIES
  import random
  import math
  import clr
  clr.AddReference('ProtoGeometry')
  from Autodesk.DesignScript.Geometry import *
  
  # DEFINE PARAMETER INPUTS
  surfIn = IN[0]
  maxSteps = IN[1]

• Fonctions :

  Copy

  def get_step_size():
    area = surfIn.Area
    stepSize = math.sqrt(area)/100
    return stepSize
  
  stepSize = get_step_size()

• Classes :

  Copy

  class MyClass:
    i = 12345
  
    def f(self):
      return 'hello world'
  
  numbers = MyClass.i
  greeting = MyClass.f

Flexibilité continue

Lors du développement de scripts de texte dans Dynamo, il est préférable de s’assurer en permanence que ce que vous créez est conforme à vos attentes. Cela permet de s’assurer que les événements imprévus (erreurs de syntaxe, écarts logiques, imprécisions de valeur, sorties anormales, etc.) sont rapidement détectés et traités dès qu’ils apparaissent, plutôt qu’en une seule fois à la fin. Comme les scripts de texte figurent dans les nœuds de la zone de dessin, ils sont déjà intégrés au flux de données de votre programme visuel. La surveillance successive de votre script est facilitée : il suffit d'attribuer des données à générer, d'exécuter le programme et d'évaluer les flux découlant du script à l'aide d'un nœud Watch. Voici quelques conseils pour inspecter en continu vos scripts au fur et à mesure de leur construction.

Testez en fonction de vos besoins :

• Chaque fois que vous complétez un cluster de fonctionnalités, procédez comme suit :

  • Revenez en arrière et examinez votre code.

  • Soyez critique. Un collaborateur peut-il comprendre à quoi sert le code ? Est-ce que j'ai besoin de faire ça ? Cette fonction peut-elle être réalisée plus efficacement ? Suis-je en train de créer des doublons ou des dépendances inutiles ?

  • Testez rapidement votre code pour vérifier qu'il renvoie des données "logiques".

• Affectez les données les plus récentes que vous utilisez dans votre script comme sortie afin que le nœud génère toujours les données pertinentes lors de la mise à jour du script :

1. Vérifiez que toutes les arêtes du solide sont renvoyées en tant que courbes pour créer une zone de contour.

2. Vérifiez que les entrées sous forme de nombres sont converties en intervalles.

3. Vérifiez que les systèmes de coordonnées ont été correctement convertis et pivotés dans cette boucle.

Anticiper les « cas extrêmes » :

• Lors du processus de script, définissez les paramètres d’entrée sur les valeurs minimale et maximale de leur domaine alloué pour vérifier si le programme fonctionne toujours dans des conditions extrêmes.

• Même si le programme fonctionne à ses extrémités, vérifiez s'il renvoie des valeurs nulles/vides/zéro non voulues.

• Parfois, les bogues et les erreurs qui révèlent un problème sous-jacent avec votre script ne se produiront que lors de ces cas extrêmes.

  • Trouvez la cause de l’erreur et déterminez si elle doit être corrigée en interne ou si un domaine de paramètre doit être redéfini pour éviter le problème.

Débogage efficace

Le débogage consiste à éliminer les "bogues" de votre script. Les bogues peuvent être des erreurs, des inefficacités, des imprécisions ou des résultats inattendus. La résolution d'un bogue peut être aussi simple que la correction d'un nom de variable mal orthographié ou des problèmes structurels plus graves avec votre script. Dans l'idéal, l'ajustement de votre script au fur et à mesure de sa construction permettra de détecter ces problèmes potentiels au plus tôt, bien que cela ne garantit pas qu'il soit exempt de bogues. Voici un examen des meilleures pratiques présentées ci-dessus pour vous aider à résoudre systématiquement les bogues.

Utilisez la bulle Watch :

• Vérifiez les données renvoyées à différents emplacements du code en l’affectant à la variable OUT, comme dans le concept d’ajustement du programme.

Écrivez des commentaires ayant du sens :

• Un module de code sera beaucoup plus facile à déboguer si le résultat attendu est clairement décrit.

# Loop through X and Y
for i in range(xCount):
  for j in range(yCount):

    # Rotate and translate the coordinate system
    toCoord = fromCoord.Rotate(solid.ContextCoordinateSystem.Origin,Vector.ByCoordinates(0,0,1),(90*(i+j%seed)))
    vec = Vector.ByCoordinates((xDist*i),(yDist*j),0)
    toCoord = toCoord.Translate(vec)

    # Transform the solid from the source coord system to the target coord system and append to the list
    solids.append(solid.Transform(fromCoord,toCoord))

On considère généralement qu’un tel exemple contient trop de commentaires et de lignes vierges, mais lors du débogage, il peut être utile de diviser le code en éléments gérables.

Utilisez la modularité du code :

• La source d’un problème peut être attribuée à certains modules.

• Une fois le module défectueux identifié, il est beaucoup plus simple de corriger le problème.

• Lorsqu'un programme doit être modifié, le code développé dans les modules sera beaucoup plus facile à modifier :

  • Vous pouvez insérer des modules nouveaux ou débogués dans un programme existant avec la certitude que le reste du programme ne changera pas.

Débogage du fichier d’exemple issu de Nœud Python.

1. Comme vous pouvez le voir lors de l’affectation de xDist et yDist à OUT, la géométrie d’entrée renvoie une zone de contour plus grande qu’elle.

2. Les courbes d'arête de la géométrie d'entrée renvoient une zone de contour appropriée avec des distances correctes pour xDist et yDist.

3. Le "module" de code inséré permet de résoudre le problème des valeurs xDist et yDist.

Exercice : Parcours le plus raide

Téléchargez le fichier d’exemple en cliquant sur le lien ci-dessous.

Vous trouverez la liste complète des fichiers d’exemple dans l’annexe.

Utilisons les meilleures pratiques en matière de script de texte pour écrire un script de simulation de pluie. Même si vous avez pu appliquer les meilleures pratiques à un programme visuel désorganisé dans Graph Strategies, il est beaucoup plus difficile de le faire avec des scripts de texte. Les relations logiques établies dans les scripts de texte sont moins visibles et sont parfois presque impossibles à délimiter dans un code désordonné. Les scripts de texte impliquent une plus grande responsabilité dans l'organisation. Vous allez effectuer chaque étape et appliquer les meilleures pratiques.

Votre script s’applique à une surface déformée par l’attraction.

La première chose à faire est d’importer les bibliothèques Dynamo nécessaires. Cette première opération permet d'accéder à la fonctionnalité Dynamo dans Python.

Toutes les bibliothèques que vous voulez utiliser doivent être importées ici.

Ensuite, vous devez définir les entrées et la sortie du script, qui s’afficheront comme ports d’entrée sur le nœud. Ces entrées externes constituent la base de votre script et la clé pour établir un environnement paramétrique.

Vous devez définir des entrées qui correspondent aux variables du script Python et déterminer une sortie souhaitée :

1. La surface à parcourir.

2. Le nombre d'agents que nous voulons voir marcher.

3. Le nombre maximal de pas que les agents sont autorisés à effectuer.

4. Une option permettant de prendre le chemin le plus court vers le bas de la surface ou de la parcourir.

5. Le nœud Python avec des identificateurs d'entrée qui correspondent aux entrées du script (IN[0], IN[1]).

6. Les courbes de sortie pouvant être affichées avec une couleur différente.

Vous allez maintenant utiliser la modularité et créer le corps de votre script. La simulation du chemin le plus court vers le bas d'une surface pour plusieurs points de départ est une tâche importante qui nécessitera plusieurs fonctions. Plutôt que d'appeler les différentes fonctions dans le script, vous pouvez modulariser votre code en les regroupant dans une classe unique, votre agent. Les différentes fonctions de cette classe ou de ce "module" peuvent être appelées avec différentes variables ou même réutilisées dans un autre script.

Vous devez définir une classe, ou un « plan », pour un agent avec l’intention de parcourir une surface en choisissant le déplacement dans la direction la plus abrupte possible à chaque fois qu’il fait un pas :

1. Nom.

2. Attributs globaux que tous les agents partagent.

3. Attributs d'instance uniques à chaque agent.

4. Fonction permettant de faire un pas.

5. Fonction permettant de cataloguer la position de chaque pas dans une liste de trajectoires.

Initialisez les agents en définissant leur emplacement de départ. C'est une bonne occasion d'ajuster votre script et de s'assurer que la classe d'agent fonctionne.

Vous devez instancier tous les agents qui doivent parcourir la surface, et définir leurs attributs initiaux :

1. Une nouvelle liste de trajectoires vide.

2. Le point de départ de leur parcours sur la surface.

3. Vous avez attribué la liste des agents comme sortie pour vérifier ce que le script renvoie ici. Le nombre correct d'agents est renvoyé, mais vous devrez ajuster le script à nouveau ultérieurement pour vérifier la géométrie qu'il renvoie.

Mettez à jour les agents à chaque pas. Vous devez ensuite entrer une boucle imbriquée où vous mettez à jour et enregistrez la position de chaque agent à chaque pas dans la liste de trajectoires correspondante. À chaque pas, vous allez également vous assurer que l'agent n'a pas atteint de point sur la surface où il ne peut plus descendre. Si cette condition est remplie, terminez le parcours de cet agent.

Maintenant que les agents ont été entièrement mis à jour, revenez à la géométrie qui les représente. Une fois que tous les agents ont atteint leur limite de descente ou leur nombre maximal de pas, vous allez créer une polycourbe à l’aide des points de leur liste de trajectoires, et générer les trajectoires polycourbes.

Votre script permettant de trouver les chemins les plus abrupts.

1. Valeur prédéfinie qui simule l’eau de pluie sur la surface sous-jacente.

2. Au lieu de trouver le chemin le plus abrupt, les agents peuvent être basculés pour parcourir la surface sous-jacente.

Le script de texte Python complet.

### STEEPEST PATH ALGORITHM

# IMPORT LIBRARIES
import sys
sys.path.append('C:\Program Files (x86)\IronPython 2.7\Lib')
import random
import math
import clr
clr.AddReference('ProtoGeometry')
from Autodesk.DesignScript.Geometry import *

# DEFINE PARAMETER INPUTS
surfIn = IN[0]
numAgents = IN[1]
maxSteps = IN[2]
decendBoo = IN[3]


# DEFINE AGENT CLASS
class Agent(object):
    def get_step_size():
        area = surfIn.Area
        stepSize = math.sqrt(area)/100
        return stepSize

    zVec = Vector.ZAxis()
    stepSize = get_step_size()
    dupTol = 0.001


    def __init__(self,u,v):
        self.endBoo = False
        self.U = u
        self.V = v
        self.Z = None
        self.trailPts = []
        self.update_trail()

    def update(self):
        if not self.endBoo:
            positionPt01 = self.trailPts[-1]
            normalVec = surfIn.NormalAtParameter(self.U,self.V)
            gradientVec = Vector.Cross(self.zVec, normalVec)
            if decendBoo:
            	gradientVec = gradientVec.Rotate(normalVec,-90)

            gradientVec = gradientVec.Normalized()
            gradientVec = gradientVec.Scale(self.stepSize)
            positionPt02 = positionPt01.Add(gradientVec)
            newPt = surfIn.ClosestPointTo(positionPt02)
            newUV = surfIn.UVParameterAtPoint(newPt)
            newU, newV = newUV.U, newUV.V
            newZ = newPt.Z

            if decendBoo and (self.Z <= newZ):
            	self.endBoo = True
            else:
	            if ((abs(self.U-newU) <= self.dupTol) and (abs(self.V-newV) <= self.dupTol)):
	                self.endBoo = True
	            else:
	                self.U, self.V = newU, newV
	                self.update_trail()

    def update_trail(self):
        trailPt = surfIn.PointAtParameter(self.U,self.V)
        self.trailPts.append(trailPt)
        self.Z = trailPt.Z


# INITIALIZE AGENTS
agents = []
for i in range(numAgents):
	u = float(random.randrange(1000))/1000
	v = float(random.randrange(1000))/1000
	agent = Agent(u,v)
	agents.append(agent)


# UPDATE AGENTS
for i in range(maxSteps):
	for eachAgent in agents:
		eachAgent.update()

# DRAW TRAILS
trails = []
for eachAgent in agents:
	trailPts = eachAgent.trailPts
	if (len(trailPts) > 1):
		trail = PolyCurve.ByPoints(trailPts)
		trails.append(trail)

# OUTPUT TRAILS
OUT = trails