Composants SketchUp : guide d’utilisation de ComponentInstance et Definition

La documentation de l’API Ruby de SketchUp explique comment les instances de composants d’un modèle sont représentées et comment gérer les définitions auxquelles elles sont liées. ComponentInstance représente une instance de composant placée dans le modèle, tandis que ComponentDefinition représente la définition sur laquelle cette instance repose. La position de l’instance dans le modèle est également déterminée par une transformation. Comprendre cette distinction aide à différencier les modifications communes à des objets réutilisés de celles qui ne concernent qu’une seule instance.

Ce guide s’appuie sur la documentation de SketchUp Ruby API consacrée à ComponentInstance, DefinitionList et Model. Les méthodes ne sont pas toutes associées aux mêmes notes de version ; lorsqu’une version précise est indiquée pour une fonctionnalité, la limite correspondante est mentionnée.

1. Comprendre le lien entre une instance et sa définition

1. Distinguez l’instance de composant présente dans le modèle de sa définition. Une ComponentInstance fait référence à un objet ComponentDefinition et porte sa propre position sous forme de transformation. Ainsi, une même définition peut être utilisée par plusieurs instances placées dans le modèle. Avant de modifier une instance, il est donc important de vérifier à quelle définition elle est liée.

2. Dans l’API Ruby, Sketchup.active_model renvoie le modèle actif. La méthode definitions de l’objet Model donne accès à la collection DefinitionList, qui contient les objets ComponentDefinition du modèle. La méthode definition d’une instance renvoie, quant à elle, la définition à laquelle cette instance est directement liée. Examiner les définitions de l’ensemble du modèle et trouver celle d’une instance précise sont donc deux opérations distinctes.

3. Si vous ne voulez pas que les autres instances utilisant la même définition soient modifiées, envisagez d’appeler make_unique avant de modifier l’instance concernée. Selon la documentation, cette méthode crée pour cette instance une nouvelle définition qui n’est utilisée par aucune autre. Cette distinction peut s’avérer utile lorsque vous souhaitez différencier un seul meuble, une seule porte ou un seul élément d’équipement parmi plusieurs exemplaires.

2. Examiner et dissocier une instance avec l’API Ruby

L’exemple ci-dessous recherche la première ComponentInstance présente dans le contexte d’édition du modèle actif. S’il en trouve une, il affiche le nom de la définition associée, puis appelle make_unique pour créer une définition indépendante pour cette instance. Le code ne parcourt pas la liste complète des définitions du modèle : il récupère le nom de la définition via la méthode definition de l’instance sélectionnée.

model = Sketchup.active_model
instance = model.active_entities.grep(Sketchup::ComponentInstance).first

if instance
  puts instance.definition.name
  instance.make_unique
end

1. Avant d’exécuter cet exemple dans votre modèle, vérifiez quel composant a été trouvé ou se trouve dans le contexte d’édition actif. Le code récupère la première ComponentInstance ; il ne sélectionne pas un composant précis par son nom. S’il y a plusieurs composants, vérifiez donc la sortie et l’instance ciblée. L’appel à make_unique ne se contente pas d’afficher une information : il crée une définition indépendante dans le modèle.

2. Modifier la définition associée et modifier la position de l’instance sont deux opérations distinctes. La méthode definition= de ComponentInstance assigne une autre définition ; la documentation précise qu’elle conserve la transformation actuelle de l’instance. Les méthodes transformation et transformation= permettent de lire ou de définir la transformation. transform! applique une Geom::Transformation, tandis que move! définit la transformation de manière similaire sans enregistrer l’opération dans la pile d’annulation. Tenez compte de cette différence lorsque vous concevez les opérations d’édition et le flux d’annulation d’une extension.

3. Manipuler avec précaution la géométrie et les collections de définitions

1. La méthode explode transforme une instance de composant en éléments de dessin distincts. Elle peut renvoyer un tableau d’éléments si l’opération réussit, ou false en cas d’échec. Si vous devez préserver la structure du composant, évaluez les conséquences de cette opération sur le modèle avant de l’utiliser. La documentation répertorie également des opérations géométriques telles que intersect, outer_shell, split, subtract, trim et union ; certaines sont conçues pour fonctionner sur des solides manifold. Il ne faut donc pas supposer qu’elles produiront le même résultat sur tous les composants.

2. trim calcule de manière non destructive la différence entre deux solides manifold ; subtract est une autre méthode répertoriée pour effectuer une opération de différence. La documentation de l’API indique également que intersect n’est pas disponible dans SketchUp Make. La méthode manifold? de ComponentInstance est marquée comme obsolète ; selon la documentation, il faut utiliser ComponentDefinition#manifold? pour vérifier si une définition est manifold. Ces remarques montrent qu’il faut consulter la description des méthodes et vérifier le type d’objet avant toute opération géométrique.

3. DefinitionList contient des méthodes permettant de rechercher des définitions par index, nom ou GUID, d’ajouter une nouvelle définition, de charger un composant depuis un fichier et de supprimer les définitions inutilisées. purge_unused supprime les définitions qui ne sont pas utilisées. Évitez de supprimer des éléments d’une collection pendant que vous la parcourez avec each : la documentation avertit que certaines définitions pourraient être ignorées, car le nombre d’éléments et les index peuvent changer. Si vous devez effectuer des suppressions, la documentation recommande de commencer par copier la collection dans un tableau, puis de travailler sur cette copie.

4. Vérifier la compatibilité des versions et la sécurité des fichiers

1. La méthode load de DefinitionList sert à charger un fichier de composant SketchUp. Selon la documentation, depuis SketchUp 2021.0, l’option allow_newer permet de charger des modèles enregistrés dans une version plus récente. Toutefois, certaines informations risquent d’être ignorées lors du chargement ; la documentation de l’API recommande de ne pas écraser le fichier chargé depuis un modèle plus récent. La préservation du modèle source doit donc faire partie du flux de travail.

2. Une note de version précise également le comportement lors du rechargement d’un composant depuis le même chemin de fichier. Avant SketchUp 2023.0, si un composant différent associé à ce chemin se trouvait déjà dans le modèle, l’appel de chargement pouvait renvoyer le composant existant au lieu de récupérer le nouveau contenu. Si le fichier ne semble pas avoir été mis à jour, vérifiez la version de SketchUp utilisée ainsi que le chemin du fichier ; tenez compte des limites de version précisées dans la documentation pour assurer la compatibilité du code de votre extension.

Conséquences pour les flux de travail en architecture, en aménagement intérieur et en visualisation

Pour les équipes d’architecture et d’aménagement intérieur qui utilisent des meubles, des portes et des équipements répétés, distinguer l’instance de sa définition aide à mieux comprendre la portée des modifications dans le modèle. Le lien avec une définition partagée est utile lorsqu’une modification commune est nécessaire ; si seule une instance doit être différenciée, make_unique est la méthode prévue à cet effet dans l’API. Cette distinction peut aider les équipes travaillant sur un modèle à suivre les éléments qui changent ensemble.

Pour les équipes de visualisation et les développeurs d’extensions, l’essentiel est également de vérifier que la bonne instance et la bonne définition ont été sélectionnées. Les sources ne précisent aucune exigence matérielle, mesure de performance ni condition de licence. Les points concrets à suivre sont la prise en charge de la méthode concernée par la version de SketchUp utilisée et la préservation du fichier source lors du chargement de fichiers issus de versions plus récentes.

Erreurs fréquentes

• Modifier la définition partagée d’une instance sans tenir compte du fait que les autres instances peuvent également être modifiées.

• Oublier que le code récupère la première ComponentInstance et supposer qu’il sélectionne un objet précis.

• Confondre l’assignation d’une définition avec la modification de la transformation de position.

• Utiliser des méthodes géométriques soumises à une condition de manifold comme si elles fonctionnaient sur tous les composants.

• Supprimer des éléments de DefinitionList pendant le parcours de la collection.

• Ignorer l’avertissement de ne pas écraser le fichier source après le chargement d’un modèle plus récent.