En bref
- Sketchup.active_model renvoie l’objet Model à utiliser pour les opérations de l’API sur le modèle ouvert.
- Model.entities désigne le contexte de dessin racine, tandis que Model.active_entities renvoie le contenu du groupe ou du composant ouvert.
- Pour parcourir une sélection, Selection#each est plus efficace que l’accès individuel aux éléments par index.
- Plusieurs instances de composant peuvent partager la même définition ; make_unique permet de rendre une seule instance indépendante.
L’API Ruby de SketchUp fournit un point de départ pour examiner et modifier les entités du modèle SketchUp ouvert. Dans la documentation officielle de l’API, les classes Model, Entities, Selection et ComponentInstance décrivent les principales façons de travailler avec le modèle, la géométrie, la sélection et les composants. Ce guide se concentre sur la mise en place de petites étapes d’automatisation maîtrisables à l’aide des méthodes présentées dans la documentation. La version de base indiquée pour ces classes est SketchUp 6.0, mais certaines méthodes ont été ajoutées dans des versions plus récentes ; il convient donc de vérifier les notes de version de la méthode utilisée.
1. Commencez par le modèle actif
Pour travailler avec l’API, récupérez d’abord l’objet correspondant au modèle ouvert. Sketchup.active_model renvoie le modèle sur lequel l’utilisateur travaille. L’objet Model donne accès aux entités de dessin, aux matériaux, aux définitions de composants et à la sélection. Cette approche permet de récupérer une seule fois les références aux collections nécessaires, plutôt que de rechercher le modèle à nouveau pour chaque opération.
model = Sketchup.active_model
entities = model.entities
materials = model.materials
definitions = model.definitions
selection = model.selectionIl est important de distinguer model.entities de model.active_entities. Le premier contient les entités de premier niveau du modèle. Si l’utilisateur a ouvert un groupe ou un composant pour le modifier, active_entities renvoie les entités du contexte en cours ; en l’absence de contexte d’édition ouvert, le résultat est identique à celui de entities. Il faut donc choisir la collection appropriée selon que l’on souhaite traiter le contenu de premier niveau du modèle ou celui que l’utilisateur est en train de modifier.
2. Examinez la sélection efficacement et en toute sécurité
model.selection représente les entités de dessin sélectionnées à ce moment-là. Pour accéder à chaque entité de la sélection, il est plus efficace de la parcourir avec each que d’appeler les index les uns après les autres. Il ne faut pas non plus supposer que l’ordre de la sélection reflète l’ordre dans lequel l’utilisateur a sélectionné les entités : la documentation précise que cet ordre n’est pas déterminé.
selection = Sketchup.active_model.selection
puts "Nombre d’éléments sélectionnés : #{selection.length}"
selection.each do |element|
puts element.typename
endSi l’opération concerne une seule entité, vous pouvez utiliser first ; cette méthode renvoie nil si la sélection est vide. empty? permet de vérifier si la sélection contient des éléments, tandis que single_object? indique si elle peut être considérée comme un objet unique. Pour vérifier si une entité est sélectionnée, utilisez include?.
Supprimer des éléments de la même collection pendant qu’on la parcourt peut en modifier la taille et les index, ce qui risque de faire sauter certaines entités. La méthode sûre recommandée dans la documentation consiste à copier d’abord les éléments à supprimer dans un tableau, puis à effectuer l’opération sur cette copie. De plus, un accès par index tel que selection[0] n’est pas efficace pour examiner chaque élément. Pour retirer des entités de la sélection ou vider celle-ci, vous pouvez utiliser remove et clear.
3. Créez la géométrie dans le bon contexte de dessin
Les nouvelles entités, comme les arêtes ou les faces, sont ajoutées à la collection Entities choisie. Par exemple, add_line crée une arête entre deux points, add_face ajoute une face et add_group crée un nouveau groupe. Utilisez model.entities pour agir au niveau racine et model.active_entities pour travailler dans le contexte d’un groupe ou d’un composant ouvert. La géométrie est ainsi ajoutée à la partie du modèle visée.
Lorsqu’une opération comprend plusieurs modifications du modèle, le mécanisme d’opérations de SketchUp permet de les enregistrer comme une action annulable. start_operation démarre une opération, commit_operation la termine et, en cas d’erreur, abort_operation peut annuler l’opération commencée. Utilisez ces méthodes pour gérer de manière cohérente plusieurs modifications indépendantes au sein d’un même flux d’automatisation.
model = Sketchup.active_model
model.start_operation("Ajouter une ligne")
begin
model.active_entities.add_line([0, 0, 0], [500, 500, 0])
model.commit_operation
rescue
model.abort_operation
raise
endLa documentation indique que abort_operation est généralement appelé dans un bloc de gestion des erreurs. Elle met toutefois en garde contre son utilisation avec les opérations transparentes : annuler une telle opération peut aussi annuler l’opération précédente à laquelle elle est liée. Si votre automatisation utilise des opérations transparentes, la gestion des erreurs doit donc être étudiée séparément.
Si vous devez créer un grand nombre d’entités géométriques, Entities#build peut également être envisagé. La documentation de l’API présente cette méthode comme un moyen de créer un EntitiesBuilder conçu pour générer des éléments géométriques en lot tout en tenant compte des performances. Il ne faut toutefois pas en déduire un gain de vitesse précis ni qu’elle convient à tous les cas, au-delà de ce qu’indique la documentation.
4. Séparez les instances de composant de leur définition
Un ComponentInstance fait référence à une définition de composant et à une transformation qui détermine sa position dans le modèle. Ainsi, une même définition peut être utilisée pour plusieurs instances. Vous pouvez, par exemple, récupérer la définition d’une instance avec definition, examiner sa transformation de positionnement avec transformation ou l’associer à une autre définition avec definition=.
Pour modifier une seule instance indépendamment des autres, vous pouvez utiliser make_unique : cette méthode crée pour l’instance concernée une définition de composant qui n’est partagée par aucune autre instance. Il faut déterminer au préalable si la modification doit s’appliquer à toutes les instances partageant la définition ou uniquement à celle qui a été sélectionnée. Sinon, la portée du changement prévu risque de ne pas correspondre au résultat obtenu dans le modèle. La méthode explode, qui transforme le composant en entités de dessin distinctes, figure également dans la documentation ; elle ne doit toutefois pas être utilisée dans les workflows où le composant doit rester une instance.
Utilisation dans les workflows d’architecture et de visualisation
Ces méthodes constituent une base pour les architectes, les architectes d’intérieur et les développeurs d’extensions SketchUp qui souhaitent automatiser les vérifications ou les modifications répétitives d’un modèle. Il est par exemple possible d’examiner les entités du contexte d’édition actif, d’évaluer collectivement les objets sélectionnés ou de créer une géométrie répétitive au sein d’une même opération. L’intérêt de cette approche dépend de la clarté avec laquelle l’automatisation définit la partie du modèle concernée et les instances affectées par une modification de composant.
La documentation ne précise aucune exigence particulière en matière de matériel ou de licence pour ces méthodes de l’API ; il ne faut donc pas supposer qu’il existe de telles exigences. Avant la mise en œuvre, vérifiez les notes relatives aux méthodes pour la version de SketchUp utilisée, en particulier celles qui portent une indication de version plus récente. Pour la génération de géométrie en lot dans de grands modèles, l’évaluation de Entities#build doit aussi s’accompagner d’une réflexion sur la gestion du workflow à l’aide d’opérations annulables.
Erreurs fréquentes
Utiliser
model.entitiesdans tous les cas : si un groupe ou un composant est ouvert pour modification,active_entitiespeut être le contexte approprié.Supposer que l’ordre de la sélection correspond à l’ordre des clics de l’utilisateur : la documentation de l’API ne le garantit pas.
Supprimer des entités de la même collection pendant un parcours avec
each: en faire d’abord une copie avecto_aévite le risque d’en sauter.Oublier qu’une définition est partagée en modifiant une instance de composant : si seule cette instance doit être indépendante, envisagez
make_unique.Annuler une opération transparente avec
abort_operation: la documentation avertit que l’opération précédente à laquelle elle est liée peut également être annulée.
Sources
3 sourcesLes textes sources ne sont pas republiés ; les courtes citations sont signalées, le reste est notre propre résumé et commentaire.
Pour les petits cabinets d’architecture et les studios de visualisation en Turquie, l’intérêt pratique de cette API tient à sa capacité à transformer des vérifications et des modifications répétitives du modèle en un flux d’automatisation. Une gestion rigoureuse de la sélection, du contexte d’édition actif et des définitions de composants peut réduire les interventions manuelles tout en limitant le risque de modifications inattendues du modèle.
Le coût de démarrage dépendra moins de l’acquisition de matériel que de la maîtrise de l’API Ruby et de son intégration aux workflows d’extensions existants ; les sources ne précisent aucune exigence particulière en matière de matériel ou de licence. Les cabinets auraient intérêt à commencer par tester sur un petit modèle l’annulation des opérations, le partage des instances de composants et la compatibilité des méthodes avec la version de SketchUp qu’ils utilisent.
Questions fréquentes
Comment accéder au modèle actif avec l’API Ruby de SketchUp ?
`Sketchup.active_model` donne accès au modèle ouvert. L’objet Model permet ensuite d’accéder à des collections comme la géométrie, la sélection, les matériaux et les définitions de composants.
Quelle est la différence entre entities et active_entities dans l’API Ruby de SketchUp ?
`entities` renvoie les entités de premier niveau du modèle. `active_entities` renvoie celles du contexte d’édition d’un groupe ou d’un composant ouvert ; s’il n’y a pas de contexte de ce type, son résultat est identique à celui de `entities`.
Comment rendre une instance de composant SketchUp indépendante des autres ?
`ComponentInstance#make_unique` crée pour cette instance une définition de composant qui n’est partagée par aucune autre. La modification peut ainsi être appliquée uniquement à l’instance rendue indépendante.



