Modellautomatisierung mit der SketchUp Ruby API: Leitfaden zu Komponenten und Geometrie

Die SketchUp Ruby API nutzt Modell-, Geometrie- und Komponentenklassen, um den Inhalt des geöffneten Modells auszulesen und zu ändern. Dieser Leitfaden zu den offiziellen Ruby-API-Dokumenten von SketchUp behandelt insbesondere den Zugriff auf Modelldaten, die Verwaltung von Komponenteninstanzen und die Bearbeitung von Geometriesammlungen. Die Dokumentation nennt für die grundlegenden Klassen die Versionsangabe SketchUp 6.0; einige Methoden setzen jedoch neuere Versionen voraus. Prüfen Sie deshalb zusätzlich die Versionshinweise der jeweiligen Methode.

1. Greifen Sie im richtigen Kontext auf den Modellinhalt zu

Ausgangspunkt eines Automatisierungs-Workflows ist das geöffnete Modellobjekt, das Sie über Sketchup.active_model erhalten. Über das Modellobjekt können Sie auf Bereiche wie die Geometrie auf oberster Ebene, Komponentendefinitionen, Materialien und die Auswahl zugreifen. So lässt sich eindeutig bestimmen, in welchem Teil des Modells sich die zu bearbeitenden Daten befinden.

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

model.entities umfasst die Zeichnungselemente auf der obersten Ebene des Modells. Bearbeitet der Benutzer gerade eine Gruppe oder Komponente, liefert model.active_entities die Elemente aus diesem aktiven Bearbeitungskontext. Ist keine Gruppe oder Komponente geöffnet, entspricht diese Sammlung entities. Diese Unterscheidung hilft dabei, Änderungen an Geometrie im falschen Kontext zu vermeiden.

Bei einem Werkzeug, das beispielsweise ausgewählte Elemente bearbeitet, kann die Auswahl die geeignete Ausgangsbasis sein. Ein Werkzeug, das im aktuellen Bearbeitungskontext arbeitet, sollte hingegen mit der Sammlung der aktiven Elemente beginnen. Ohne den Umfang der Operation festzulegen, direkt den gesamten Modellinhalt zu ändern, kann unerwünschte Änderungen zur Folge haben.

2. Komponentendefinition und Instanz unterscheiden

Bei SketchUp-Komponenten sind Definition und Instanz nicht dasselbe. ComponentDefinition definiert die Elemente einer Komponente; ComponentInstance steht für eine Platzierung dieser Definition im Modell samt ihrer Transformation. Von derselben Definition können mehrere Instanzen erstellt werden. Änderungen an der Definition wirken sich auf die Instanzen aus, die sie verwenden.

Mit der Methode definition können Sie herausfinden, an welche Definition eine Instanz gebunden ist. Es ist auch möglich, eine Instanz einer anderen Definition zuzuweisen. Laut Dokumentation bleibt dabei die Transformation der Instanzposition im Modell erhalten.

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

In diesem Beispiel wird vorausgesetzt, dass es sich beim ersten Element um eine Komponenteninstanz handelt. In einem tatsächlichen Plugin sollte der Typ jedes Elements in der Sammlung geprüft und der mögliche Fall eines leeren Ergebnisses berücksichtigt werden. Mit den Methoden count_instances und count_used_instances können Sie über die Komponentendefinition deren Verwendung zählen: Die erste zählt unterschiedliche Instanzen, die zweite die Gesamtzahl der Instanzen im Modell, die diese Definition verwenden.

Wenn eine einzelne Instanz unabhängig bearbeitet werden soll, können Sie make_unique verwenden. Diese Methode erstellt für die betreffende Instanz eine Definition, die nicht mit anderen Instanzen geteilt wird. Legen Sie daher vor einer gemeinsamen Bearbeitung fest, ob die Änderung für die gemeinsame Definition oder nur für die ausgewählte Instanz gelten soll.

3. Geometriesammlungen effizient bearbeiten

Entities ist eine Sammlung von Elementen in einem Modell oder einer Komponentendefinition. Laut Dokumentation ist es im Allgemeinen effizienter, Elemente mit der Methode each zu durchlaufen, statt sie über Indizes abzurufen. Bei Skripten, die eine Sammlung durchsuchen, ist dieser Ansatz außerdem gut lesbar.

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

Wenn der Zugriff über einen bestimmten Index erforderlich ist, können Sie entities[index] verwenden. Ein gültiger Index liegt jedoch zwischen null und der Sammlungsgröße minus eins; wird kein Element gefunden, kann die Methode nil zurückgeben. Bei Operationen, die von einem vom Benutzer gewählten Index abhängen, sollten Sie daher dieses Ergebnis prüfen.

Zum Erstellen einer einzelnen Linie gibt es Methoden wie add_line, für einen Kreis add_circle und für eine Fläche add_face. Um zahlreiche Geometrieelemente mit Blick auf die Performance zu erzeugen, erstellt die Methode Entities#build ein EntitiesBuilder-Objekt. Die Dokumentation beschreibt diese Methode für die Erzeugung größerer Geometriemengen, nennt jedoch weder einen bestimmten Geschwindigkeitszuwachs noch Hardwareanforderungen. Der tatsächliche Nutzen sollte daher mit der verwendeten Geometrie und dem Plugin-Workflow im konkreten Projekt gemessen werden.

Wenn die Operation als rückgängig zu machender Schritt erfasst werden soll, können Sie auf Modellebene die Methoden start_operation und commit_operation verwenden. Für den Fehlerfall zeigt die offizielle Dokumentation abort_operation, um die gestartete Operation abzubrechen. Außerdem weist die Dokumentation darauf hin, dass eine transparente Operation nicht abgebrochen werden sollte.

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. Einsatz in Architektur- und Visualisierungs-Workflows

In der Architekturmodellierung und bei Innenraumprojekten kann diese API genutzt werden, um wiederkehrende Elemente als Komponenten zu organisieren, Modellinhalte zu prüfen und wiederholte Geometrieoperationen per Skript auszuführen. Um beispielsweise verschiedene Platzierungen derselben Möbeld efiniton zu verwalten, müssen Definition und Instanz korrekt voneinander unterschieden werden. Soll ein Element unabhängig gemacht werden, kommt make_unique infrage; für gemeinsame Aktualisierungen sollte dagegen die gemeinsam genutzte Definition in Betracht gezogen werden.

Bei der Entwicklung eines Automatisierungsskripts für ein Büro sollte zunächst der Umfang festgelegt werden: Wird die Geometrie des Modellstamms, der Inhalt einer geöffneten Gruppe oder die Auswahl bearbeitet? Anschließend ist die Beziehung zwischen Komponentendefinition und Instanz zu berücksichtigen. Um die Kompatibilität des Plugins mit der SketchUp-Version sicherzustellen, sollten Sie die Versionsangaben der verwendeten Methoden in der offiziellen Dokumentation prüfen. Da die Dokumentation keine bestimmten Hardwareanforderungen nennt, lässt sich keine spezielle Hardwareempfehlung ableiten. Bei umfangreichen Geometrieoperationen ist es sinnvoller, die Performance am Zielmodell zu testen.

Häufige Fehler

• Die Sammlungen entities und active_entities so verwenden, als hätten sie denselben Umfang.

• Nicht berücksichtigen, dass Änderungen an einer gemeinsamen Definition auf Komponenteninstanzen übertragen werden.

• Übersehen, dass für ein Element, das über einen Index abgerufen wird, kein Ergebnis gefunden werden kann und der Rückgabewert dann nil sein kann.

• Nach dem Start einer Operation im Erfolgsfall commit_operation und im Fehlerfall den passenden Abschluss nicht verwalten.

Dieser Leitfaden basiert auf den dokumentierten grundlegenden Modell-, Komponenten- und Geometrieklassen der SketchUp Ruby API. Da die hier behandelten Dokumentationsabschnitte keine Angaben zu Menüpfaden, Lizenzbedingungen oder Hardwareanforderungen enthalten, werden dazu keine Annahmen getroffen.