Automatiser les modèles avec l’API Ruby de SketchUp : composants et géométrie

L’API Ruby de SketchUp s’appuie sur des classes de modèle, de géométrie et de composants pour lire et modifier le contenu du modèle ouvert. Ce guide, fondé sur la documentation officielle de l’API Ruby de SketchUp, porte notamment sur l’accès aux données du modèle, la gestion des instances de composants et les opérations sur les collections de géométrie. La documentation indique SketchUp 6.0 comme version de référence pour les classes essentielles, mais certaines méthodes sont soumises à des exigences de version plus récente ; il convient donc de vérifier séparément la note de version de chaque méthode utilisée.

1. Accéder au contenu du modèle dans le bon contexte

Le point de départ d’un flux d’automatisation est l’objet du modèle ouvert, obtenu avec Sketchup.active_model. Cet objet permet d’accéder à des éléments tels que la géométrie racine, les définitions de composants, les matériaux et la collection de sélection. Il devient ainsi plus facile de déterminer dans quelle partie du modèle se trouvent les données à traiter.

model = Sketchup.active_model
entities = model.entities
definitions = model.definitions
materials = model.materials
selection = model.selection

model.entities comprend les entités de dessin situées à la racine du modèle. Si l’utilisateur modifie un groupe ou un composant, model.active_entities renvoie les entités de ce contexte d’édition. Si aucun groupe ou composant n’est ouvert, cette collection est identique à entities. Cette distinction aide à éviter que la commande ne modifie la géométrie dans le mauvais contexte.

Par exemple, pour un outil qui agit sur les entités sélectionnées, la collection de sélection peut servir de point de départ. Pour un outil qui opère dans le contexte d’édition actuel, mieux vaut utiliser la collection des entités actives. Modifier directement tout le contenu du modèle sans avoir défini la portée de l’opération peut entraîner des changements indésirables.

2. Distinguer la définition d’un composant de son instance

Dans SketchUp, la définition et l’instance d’un composant sont deux choses différentes. ComponentDefinition décrit les entités qui composent le composant ; ComponentInstance représente l’emplacement et la transformation d’une occurrence de cette définition dans le modèle. Une même définition peut donner lieu à plusieurs instances. Les modifications apportées à la définition sont répercutées sur les instances qui l’utilisent.

Vous pouvez déterminer à quelle définition une instance est associée avec la méthode definition. Il est également possible de basculer une instance vers une autre définition ; la documentation précise que la transformation de positionnement de l’instance dans le modèle est conservée lors de cette modification.

instance = model.entities[0]
definition = instance.definition
puts definition.name

Cet exemple suppose que la première entité est une instance de composant. Dans une véritable extension, il faut vérifier le type de chaque entité de la collection et gérer le cas où le résultat est vide. Les méthodes count_instances et count_used_instances de la définition d’un composant permettent d’en compter les utilisations : la première compte les instances distinctes, la seconde le nombre total d’instances du modèle qui utilisent cette définition.

La méthode make_unique permet de modifier une seule instance de manière indépendante. Elle crée pour cette instance une définition qui n’est pas partagée avec les autres. Avant d’effectuer des modifications en série, il faut donc décider si elles doivent s’appliquer à la définition partagée ou uniquement à l’instance sélectionnée.

3. Traiter efficacement les collections de géométrie

Entities est une collection d’entités présentes dans le modèle ou dans une définition de composant. La documentation indique qu’en règle générale, il est plus efficace de parcourir les entités avec each que d’y accéder une par une à l’aide d’un index. Cette approche permet aussi de suivre un flux plus lisible dans les scripts qui parcourent une collection.

model.entities.each do |entity|
  puts entity.typename
end

Pour accéder à un index précis, vous pouvez utiliser entities[index]. Toutefois, l’index doit être compris entre zéro et la longueur de la collection moins un ; si aucune entité ne correspond, la méthode peut renvoyer nil. Il est donc important de vérifier le résultat lorsque l’opération dépend d’un index fourni par l’utilisateur.

Des méthodes comme add_line pour créer une ligne, add_circle pour un cercle ou add_face pour une face sont disponibles. Pour générer un grand nombre d’entités géométriques en tenant compte des performances, la méthode Entities#build crée un EntitiesBuilder. La documentation présente cette méthode comme destinée à la création de géométrie en masse, mais ne précise ni gain de vitesse particulier ni exigences matérielles. Il convient donc de mesurer son intérêt dans le contexte du projet, avec la géométrie et le flux de l’extension concernés.

Pour enregistrer une opération comme une étape réversible, vous pouvez utiliser les méthodes start_operation et commit_operation au niveau du modèle. En cas d’erreur, la documentation officielle indique d’annuler l’opération démarrée avec abort_operation. Elle précise également qu’une opération transparente ne doit pas être annulée.

model.start_operation("Model düzenlemesi")
begin
  # Geometri işlemlerini burada yürütün.
  model.commit_operation
rescue
  model.abort_operation
  raise
end

4. Utilisation dans les flux de travail architecturaux et de visualisation

Dans les projets d’architecture et d’aménagement intérieur, cette API peut servir à organiser des éléments répétitifs en composants, à examiner le contenu d’un modèle et à exécuter des opérations géométriques récurrentes à l’aide de scripts. Par exemple, gérer différentes dispositions d’une même définition de mobilier exige de bien distinguer la définition de l’instance. Si un élément doit être rendu indépendant, l’option make_unique peut être envisagée ; si une mise à jour commune est souhaitée, il faut plutôt conserver une définition partagée.

Lors du développement d’un script d’automatisation pour un bureau, il faut d’abord définir la portée : s’agit-il de traiter la géométrie racine du modèle, le contenu d’un groupe ouvert ou les entités sélectionnées ? Il faut ensuite tenir compte de la relation entre la définition du composant et ses instances. Pour vérifier la compatibilité de l’extension avec la version de SketchUp utilisée, consultez les informations de version des méthodes dans la documentation officielle. Celle-ci ne précisant aucune exigence matérielle particulière, il n’est pas possible de formuler une recommandation spécifique en la matière ; pour les opérations géométriques intensives, il est préférable d’évaluer les performances sur le modèle cible.

Erreurs fréquentes

• Utiliser les collections entities et active_entities comme si elles correspondaient au même périmètre.

• Ne pas tenir compte du fait qu’une modification de la définition partagée sera répercutée sur les instances du composant.

• Oublier que l’entité obtenue par index peut être introuvable et que le résultat peut alors être nil.

• Après le démarrage d’une opération, ne pas gérer commit_operation en cas de réussite ou l’étape de clôture appropriée en cas d’erreur.

Ce guide s’appuie sur les classes essentielles de modèle, de composant et de géométrie documentées dans l’API Ruby de SketchUp. Les extraits de documentation consultés ne décrivant ni les chemins d’accès aux menus de l’interface, ni les conditions de licence, ni les exigences matérielles, aucune hypothèse n’a été formulée à ce sujet.