Comment utiliser Python dans Dynamo pour accéder à l’API Revit
Les nœuds visuels de Dynamo couvrent la majorité des besoins — mais certaines opérations complexes nécessitent du code. Le nœud Python Script vous donne accès à l’API Revit complète : boucles imbriquées, conditions multiples, accès à des méthodes non exposées par les nœuds natifs, performances supérieures sur de grands ensembles de données. Ce guide vous montre comment franchir le pas du visuel au code, étape par étape, avec des exemples concrets.
Quand passer au Python dans Dynamo ?
La règle d’or : restez en nœuds visuels tant que c’est possible. Un script visuel est plus lisible, plus maintenable par vos collègues non-programmeurs, et plus facile à déboguer. Passez au Python uniquement quand vous atteignez les limites des nœuds natifs.
Les bonnes raisons de passer au Python
- Accès à des méthodes API non exposées : certaines opérations Revit n’ont pas de nœud Dynamo correspondant (créer des filtres de vue par programme, manipuler les paramètres BuiltIn, accéder aux données de phase).
- Logique conditionnelle complexe : des conditions imbriquées sur plusieurs niveaux créent un canvas illisible en visuel. En Python, 10 lignes de code remplacent 30 nœuds enchevêtrés.
- Performances : sur des modèles de plusieurs milliers d’éléments, un script Python bien écrit est souvent 2 à 10 fois plus rapide qu’un enchaînement de nombreux nœuds Dynamo.
- Manipulation de données complexes : trier, filtrer, agréger des données avec des critères multiples est beaucoup plus naturel en Python qu’avec les nœuds de liste Dynamo.
- Intégration avec des bibliothèques Python : accès à des bibliothèques comme
json,csv,os,datetimepour manipuler des fichiers et des données externes.
Syntaxe de base : IN, OUT et UnwrapElement
Le nœud Python Script dans Dynamo a une interface spécifique. Il possède des ports d’entrée (IN[0], IN[1], IN[2]…) que vous connectez à des nœuds Dynamo, et un unique port de sortie (OUT) qui renvoie le résultat vers le canvas. Double-cliquez sur le nœud Python Script pour ouvrir l’éditeur de code.
import clr — importe le Common Language Runtime pour accéder aux bibliothèques .NET
clr.AddReference('RevitAPI') — charge la bibliothèque de l’API Revit
clr.AddReference('RevitAPIUI') — charge l’interface utilisateur de l’API (optionnel)
from Autodesk.Revit.DB import * — importe toutes les classes Revit
doc = __revit__.ActiveUIDocument.Document — référence au document Revit actif
elements = UnwrapElement(IN[0]) — convertit les éléments Dynamo en objets Revit natifs
# Votre logique ici
OUT = result — renvoie le résultat vers Dynamo
Le rôle critique d’UnwrapElement
C’est l’erreur la plus fréquente chez les débutants : les éléments qui arrivent par les ports IN ne sont pas des objets Revit natifs. Ce sont des « wrappers » Dynamo — des enveloppes qui contiennent l’élément Revit mais ne l’exposent pas directement. Sans UnwrapElement(), les méthodes de l’API Revit (comme element.get_Parameter()) ne fonctionneront pas.
Règle simple : appelez toujours UnwrapElement() sur les éléments que vous recevez de Dynamo avant de les utiliser avec l’API Revit. Pour une liste d’éléments : elements = [UnwrapElement(e) for e in IN[0]].
Gérer les entrées simples et les listes
Un port IN peut recevoir une valeur unique ou une liste, selon ce qui est connecté. Pour gérer les deux cas : utilisez isinstance(IN[0], list) pour détecter si l’entrée est une liste. Alternativement, normalisez toujours en liste au début du script : elements = IN[0] if isinstance(IN[0], list) else [IN[0]].
Accéder à l’API Revit depuis Python
L’API Revit expose des milliers de classes, propriétés et méthodes pour interagir avec le modèle. La documentation de référence absolue est le site revitapidocs.com — un site communautaire qui liste toutes les classes et méthodes de l’API avec leur description et des exemples de code C# (facilement adaptables en Python).
Les classes les plus utilisées
FilteredElementCollector: le collecteur d’éléments le plus puissant de l’API. Permet des filtrages précis par catégorie, type, classe, paramètre — souvent plus performant que les nœuds Dynamo natifs.Element.get_Parameter(BuiltInParameter.XXX): accès aux paramètres intégrés Revit par leur identifiant système. Plus précis que l’accès par nom (qui peut être ambigu).ElementId: l’identifiant unique d’un élément. Indispensable pour retrouver un élément spécifique ou construire des relations entre éléments.Wall.Create(),Floor.Create(): création d’éléments Revit par code — pour les scripts de génération géométrique avancée.Transaction: encapsule les modifications du modèle (voir section suivante).
Utiliser FilteredElementCollector depuis Python
Exemple : récupérer tous les murs du document actif directement en Python, sans passer par un nœud Dynamo en entrée :
collector = FilteredElementCollector(doc)
walls = collector.OfClass(Wall).ToElements()
wall_ids = [w.Id.IntegerValue for w in walls]
OUT = wall_ids
Ce script retourne la liste des ElementId (entiers) de tous les murs du projet. Variante avec filtre par catégorie : .OfCategory(BuiltInCategory.OST_Walls) — légèrement différent, retourne les instances et les types selon la catégorie.
Transactions : modifier le modèle en Python
Toute modification du modèle Revit (écriture de paramètre, création ou suppression d’élément) doit s’effectuer dans une transaction. Sans transaction ouverte, l’API Revit lèvera une exception et votre script plantera.
Dans le nœud Python Script de Dynamo, les transactions sont généralement gérées automatiquement par Dynamo lorsque vous utilisez des nœuds Dynamo en amont ou aval. N’ouvrez une transaction manuelle que si vous rencontrez une erreur du type « Autodesk.Revit.Exceptions.InvalidOperationException: The document is not in a valid state for modification ». La double ouverture de transaction (ouvrir une Transaction quand une est déjà active) est une erreur fréquente qui plante le script. En cas de doute, utilisez TransactionManager.Instance.EnsureInTransaction(doc) — il ne s’ouvre que si aucune transaction n’est déjà active.
Transaction manuelle quand nécessaire
import TransactionManager from Dynamo.Applications — non, la bonne approche est :
TransactionManager.Instance.EnsureInTransaction(doc) — ouvre une transaction si nécessaire
# vos modifications ici
TransactionManager.Instance.TransactionTaskDone() — valide la transaction
Alternative avec Transaction native : t = Transaction(doc, "Nom de ma transaction") / t.Start() / modifications / t.Commit()
Exemples concrets de scripts Python-Dynamo
Renommer des feuilles avec un préfixe
Objectif : ajouter le préfixe « ARCH- » au nom de toutes les feuilles dont le nom ne commence pas déjà par ce préfixe.
- Récupérez toutes les feuilles avec
FilteredElementCollector(doc).OfClass(ViewSheet).ToElements(). - Lisez le nom avec
sheet.get_Parameter(BuiltInParameter.SHEET_NAME).AsString(). - Testez avec
if not name.startswith("ARCH-"). - Écrivez le nouveau nom avec
param.Set("ARCH-" + name).
Identifier les vues non placées sur feuille
Collectez toutes les vues du projet. Pour chaque vue, vérifiez si sa propriété IsOnSheet (via BuiltInParameter.VIEWER_SHEET_NUMBER) est vide ou null. Retournez la liste des vues non placées dans OUT. Ce script constitue la base d’un outil d’audit de modèle automatisé.
Créer des filtres de vue par valeur de paramètre
L’API Revit expose ParameterFilterElement.Create() pour créer des filtres de vue par programme. Ce cas d’usage n’a pas de nœud natif Dynamo — Python est la seule voie. Vous pouvez générer automatiquement un filtre par zone, par lot ou par phase depuis une liste de valeurs lue dans Excel.
Maîtrisez Python pour l’API Revit
Notre formation Dynamo Avancé couvre le nœud Python Script, l’API Revit, les transactions et les automatisations complexes.
Voir la formation Dynamo →Bonnes pratiques de développement Python dans Dynamo
Commentez votre logique métier, pas la syntaxe : un script relu 6 mois plus tard doit s’expliquer par ses commentaires. Écrivez « # Filtre les pièces sans finition définie » et non « # boucle for ».
Gérez les erreurs avec try/except : un élément problématique ne doit pas faire planter tout le script. Enveloppez votre logique principale dans un bloc try/except et loggez les erreurs dans une liste OUT[1] pour diagnostic.
Appelez toujours UnwrapElement() sur les entrées Dynamo avant d’utiliser les méthodes de l’API Revit.
Testez incrémentalement : écrivez 5 lignes, vérifiez le résultat dans un nœud Watch, puis continuez. Ne codez pas 50 lignes d’un coup avant de tester.
Limitez les éléments traités pendant le développement : ajoutez en début de script elements = elements[:5] pour ne traiter que les 5 premiers éléments. Supprimez cette ligne une fois le script validé.
Déboguer un script Python dans Dynamo
Dynamo n’a pas de débogueur Python intégré. Les techniques de débogage disponibles :
- Retourner des valeurs intermédiaires : assignez
OUT = ma_variable_intermediairepour inspecter son contenu dans un nœud Watch. - Utiliser plusieurs sorties : le nœud Python Script n’a qu’un seul port OUT, mais vous pouvez retourner une liste :
OUT = [resultat, erreurs, debug_info]et connecter plusieurs nœuds Watch aux indices de cette liste. - Écrire dans un fichier log :
with open(r"C:\temp\dynamo_debug.txt", "a") as f: f.write(str(ma_variable) + "\n")— permet de tracer l’exécution sans modifier la sortie du nœud.
Ressources pour apprendre l’API Revit
- revitapidocs.com : la référence communautaire de l’API Revit, indexée et recherchable.
- thebuildingcoder.typepad.com : le blog de Jeremy Tammik (Autodesk), des centaines d’exemples C# adaptables en Python.
- Le forum Dynamo (forum.dynamobim.com) : des milliers de questions-réponses sur le Python dans Dynamo.
- Dynamo Primer (primer.dynamobim.org) : le guide officiel, avec un chapitre dédié aux scripts Python.
Questions fréquentes sur Python dans Dynamo
Quelle version de Python est utilisée dans le nœud Python Script ?
Dynamo utilise IronPython (une implémentation Python pour .NET), version 2.7 dans les versions de Dynamo antérieures à 2.16, et Python 3 via CPython dans les versions récentes (Dynamo 2.13+ avec CPython 3.8). La version exacte dépend de votre version de Dynamo. Vérifiez dans Dynamo → Settings → Manage Node and Package Paths → Python Engine. Certains packages et scripts sont écrits pour l’un ou l’autre — la migration de Python 2 vers Python 3 peut nécessiter des ajustements syntaxiques.
Peut-on utiliser des bibliothèques Python tierces (numpy, pandas) dans Dynamo ?
Avec IronPython (version 2.7), l’accès aux bibliothèques tierces est limité aux bibliothèques compatibles .NET. Numpy et pandas ne fonctionnent pas directement. Avec CPython 3 (versions récentes de Dynamo), l’accès aux bibliothèques Python standard s’améliore, mais certaines bibliothèques nécessitant des extensions C restent problématiques. Pour des traitements de données avancés, privilégiez l’approche Excel ou JSON pour échanger les données avec un script Python externe.
Comment déboguer une erreur dans le nœud Python Script ?
Dynamo affiche le message d’erreur Python dans le tooltip du nœud en erreur (survol de la souris). Lisez attentivement le type d’exception et le numéro de ligne. Les erreurs les plus courantes : AttributeError (méthode inexistante sur l’objet), InvalidOperationException (transaction non ouverte), NullReferenceException (objet null non vérifié). Retournez des valeurs intermédiaires dans OUT pour inspecter l’état de vos variables à chaque étape.
Python dans Dynamo vs Revit Macro vs pyRevit : quelle différence ?
Python dans Dynamo s’exécute dans le contexte d’un script visuel Dynamo — idéal pour les automatisations ponctuelles. Les Revit Macros (via SharpDevelop dans l’onglet Gérer) s’exécutent directement dans Revit sans Dynamo, en C# ou VB. pyRevit est un framework externe qui permet de créer des boutons de ruban Revit avec du Python — idéal pour les outils permanents distribués en équipe. Pour les automatisations BIM du quotidien, Dynamo + Python est souvent le meilleur rapport effort/résultat.
Sources et références
- revitapidocs.com — Documentation communautaire de l’API Revit
- Dynamo Primer — Chapitre Python Script — primer.dynamobim.org
- thebuildingcoder.typepad.com — Jeremy Tammik, Autodesk Developer Advocate
- forum.dynamobim.com — Forum officiel Dynamo, section Python
- Autodesk Knowledge Network — Python Engine in Dynamo
