Créer des pièces et examiner leurs limites avec l’API Revit : guide pour débutants

Que découvrirez-vous dans ce guide ?

Ce guide s’adresse aux personnes qui souhaitent comprendre les notions de catégorie et de pièce dans l’API Revit, et interpréter correctement les exemples de la documentation développeur d’Autodesk. Nous verrons d’abord comment un élément Revit est classé en catégorie, famille, type et instance. Nous présenterons ensuite deux méthodes de création de pièces avec l’API et les conditions à vérifier pour lire leurs limites.

L’objectif n’est pas de fournir un module prêt à l’emploi qui fonctionnera dans tous les projets. Les exemples de code montrent les objets et les conditions de projet avec lesquels l’API fonctionne. Les exemples des sources sont écrits en C# ; il ne faut donc pas les coller dans un outil Python comme s’il s’agissait de code Python.

Prérequis et périmètre

La formation d’initiation d’Autodesk University utilise Revit, RevitPythonShell, Revit Lookup et pyRevit. Elle indique qu’il faut connaître les bases de Revit et avoir un niveau débutant en Python. Cela ne signifie pas que les exemples d’API présentés ci-dessous sont en Python : les extraits de code des documents Autodesk sur les pièces et les catégories sont fournis en C#.

L’un des documents développeur cités concerne Revit 2018, l’autre est une page de la documentation Revit 2024. Les sources ne précisent pas la compatibilité de ces exemples avec les différentes versions de Revit. Avant d’utiliser un exemple dans un projet réel, vérifiez donc la documentation de l’API correspondant à la version cible. Les sources fournies ne précisent ni les exigences liées au compte, ni les versions actuelles des outils, ni leurs conditions de licence.

1. Distinguer catégories et structure des familles

Une catégorie classe un élément selon son type général et la manière dont Revit le traite. Les murs, les portes et les pièces sont des exemples de catégories différentes. Les catégories sont liées à des fonctions telles que la création de nomenclatures, la gestion des paramètres ou le contrôle de la visibilité et de l’affichage graphique.

La structure des familles est plus détaillée. Family représente la famille dans son ensemble, FamilySymbol un type spécifique de cette famille et FamilyInstance une instance placée dans le projet. Par exemple, une famille de portes peut comprendre plusieurs types ; chaque porte placée dans le projet est quant à elle considérée comme une instance. Dans l’API, cette distinction permet de ne pas confondre la catégorie générale d’un élément avec son type particulier.

L’exemple d’Autodesk consacré aux catégories montre comment accéder à la collection de catégories du document ouvert et sélectionner une catégorie intégrée. La documentation avertit également que les noms de catégories peuvent varier selon la langue de l’interface Revit. Pour éviter les différences linguistiques, envisagez d’utiliser des identifiants de catégorie intégrés tels que BuiltInCategory plutôt que de vous appuyer sur le texte du nom.

2. Choisir une méthode de création de pièce

La documentation de l’API décrit deux scénarios distincts pour créer une pièce. Dans le premier, la pièce est créée à partir d’un niveau et d’un emplacement. L’exemple exprime l’emplacement au moyen d’une valeur de type UV et vérifie si le résultat de la création est valide. L’idée essentielle est que l’appel de création dépend non seulement de l’objet pièce, mais aussi des informations indiquant le niveau et l’emplacement auxquels elle doit se trouver.

Dans le second scénario, une pièce est d’abord créée dans une nomenclature de pièces et associée à une phase du projet ; elle est ensuite ajoutée à un circuit de plan. La condition importante est que l’élément à ajouter au plan figure uniquement dans la nomenclature des pièces et ne soit encore présent dans aucune vue en plan. Le circuit de plan est trouvé à partir de la topologie du plan du niveau concerné. Une fois le placement réussi, une pièce du modèle portant le même nom et le même numéro est créée dans la vue où se trouve le circuit de plan.

Avant d’appliquer ces deux méthodes, déterminez le résultat recherché : créer une pièce à un emplacement précis ou placer dans un circuit de plan une pièce en attente dans la nomenclature ? Dans le second flux, si la pièce ne figure pas dans la nomenclature, l’opération risque de ne pas fonctionner avec les entrées attendues.

3. Examiner les limites des pièces et leur mise à jour

Les limites d’une pièce dépendent des éléments du modèle qui forment une zone fermée. Dans la documentation Autodesk, des éléments tels que les murs, les lignes de modèle, les poteaux et les toits sont cités parmi ceux qui peuvent définir une limite. La méthode SpatialElement.GetBoundarySegments() permet de lire les segments de limite. Les données renvoyées peuvent contenir une ou plusieurs zones et les segments de chacune d’elles, sous forme de listes imbriquées.

Les données de limite ne sont pas toujours renvoyées. Si la pièce ne se trouve pas dans une zone fermée ou figure uniquement dans une nomenclature de pièces, la méthode peut renvoyer null. Si aucun résultat n’est obtenu, vérifiez donc non seulement l’appel à l’API, mais aussi si le modèle forme une pièce fermée et si la pièce est présente dans une vue en plan.

Le paramètre Room Bounding détermine si des éléments tels que les murs, les poteaux et les toits contribuent aux limites des pièces. Les lignes de séparation de pièce peuvent également définir des limites. Lorsqu’un élément tel qu’un mur est ajouté via l’API, les limites de la pièce peuvent changer : ne considérez donc pas comme à jour les informations de limite obtenues avant cette modification. L’exemple Autodesk montre que les limites sont relues après la création de l’élément, une fois l’opération terminée dans une transaction.

Il est également possible de retirer d’abord une pièce de son emplacement actuel pour la déplacer. La documentation explique que la méthode Room.Unplace() permet de retirer la pièce de son emplacement tout en la conservant dans le projet. Il faut donc comprendre la différence entre supprimer l’objet du projet et modifier son emplacement.

4. Incidence sur les flux de travail en architecture et en visualisation

Comprendre les limites des pièces et les relations entre catégories peut aider les équipes d’architecture et d’architecture intérieure qui travaillent avec les données des pièces, classent les éléments du modèle ou envisagent d’automatiser des opérations répétitives. Comme les limites des pièces dépendent des éléments environnants du modèle et de leurs paramètres, il faut vérifier ces relations avant de commencer l’automatisation.

Ces sources ne décrivent pas directement des paramètres de rendu ou de visualisation. Toutefois, la cohérence du modèle est importante dans les processus BIM qui utilisent les données des pièces et des catégories. Avant la mise en œuvre, examinez la version de Revit utilisée, l’état de placement de la pièce, les paramètres Room Bounding concernés et la phase du projet. Pour les étudiants, un petit modèle de test constitue un bon point de départ pour observer l’incidence d’une modification d’un mur ou d’un autre élément environnant sur les données de limite.

Erreurs fréquentes

• Supposer que les noms de catégories sont identiques dans toutes les langues de Revit. Autodesk recommande d’utiliser les identifiants de catégorie intégrés pour éviter les différences linguistiques.

• Attendre des segments de limite alors que la pièce ne se trouve pas dans une zone fermée. Selon la documentation, la méthode peut dans ce cas renvoyer null.

• Placer dans une vue en plan la pièce qui doit être ajoutée à un circuit de plan. L’élément d’entrée doit figurer uniquement dans la nomenclature des pièces.

• Négliger le paramètre Room Bounding des éléments environnants. Ce paramètre détermine si l’élément contribue ou non aux limites de la pièce.

• Continuer à utiliser les anciennes données de limite après la création d’un nouvel élément du modèle. Relisez les données de limite une fois la modification terminée.

• Traiter les exemples C# comme du code Python. Bien que les sources mentionnent des outils Python, les exemples d’API sur les pièces et les catégories sont écrits en C#.

Étapes suivantes

Commencez par consulter les explications d’Autodesk sur les catégories et observez, dans un projet existant, la distinction entre catégorie, famille, type et instance. Comparez ensuite les scénarios de création de pièces dans un document de test : création à partir d’un emplacement et placement depuis la nomenclature vers un circuit de plan. À chaque étape, notez dans quelle vue se trouve la pièce.

Enfin, modifiez les éléments autour d’une zone fermée de pièce et vérifiez à nouveau les données de limite. Cet exercice permet de ne pas considérer la valeur renvoyée par l’API indépendamment de l’état du modèle. Avant de passer à des automatisations plus avancées, étudiez également les filtres d’éléments, les transactions et les interfaces utilisateur abordés dans la formation d’initiation d’Autodesk University.

Sources et licence

Ce guide a été rédigé avec nos propres formulations à partir des documents développeur Autodesk Revit API sur les pièces (K1), la classification des catégories et des familles (K2), ainsi que de la formation d’initiation à l’API Revit d’Autodesk University (K4). Les sources sont indiquées comme libres de droits ; comme les textes fournis ne précisent pas de licence particulière, aucune licence spécifique ne leur est attribuée ici.