Kurz gesagt
- Sketchup.active_model gibt das Model-Objekt für API-Aufrufe im geöffneten Modell zurück.
- Model.entities liefert den obersten Zeichenkontext, Model.active_entities den Inhalt der geöffneten Gruppe oder Komponente.
- Mit Selection#each über die Auswahl zu iterieren ist effizienter, als die Elemente einzeln über ihre Indizes abzurufen.
- Komponenteninstanzen können dieselbe Definition verwenden; mit make_unique lässt sich eine einzelne Instanz davon unabhängig machen.
Die SketchUp Ruby API bietet einen Einstiegspunkt, um Zeichnungselemente im geöffneten SketchUp-Modell zu untersuchen und zu ändern. In der offiziellen API-Dokumentation erläutern die Klassen Model, Entities, Selection und ComponentInstance grundlegende Methoden für die Arbeit mit Modell, Geometrie, Auswahl und Komponenten. Dieser Leitfaden konzentriert sich darauf, mit den dokumentierten Methoden kleine, nachvollziehbare Automatisierungsschritte umzusetzen. Für die grundlegenden Klassen ist SketchUp 6.0 als Version angegeben; einige Methoden wurden jedoch erst in neueren Versionen ergänzt. Prüfen Sie deshalb zusätzlich die Versionshinweise der jeweils verwendeten Methode.
1. Mit dem aktiven Modell beginnen
Rufen Sie zunächst das Objekt des geöffneten Modells ab, wenn Sie mit der API arbeiten. Sketchup.active_model gibt das Modell zurück, an dem der Benutzer gerade arbeitet. Über das Model-Objekt können Sie auf Zeichnungselemente, Materialien, Komponentendefinitionen und die Auswahl zugreifen. So können Sie zu Beginn auf die benötigten Sammlungen verweisen, statt das Modell bei verschiedenen Vorgängen immer wieder neu abzurufen.
model = Sketchup.active_model
entities = model.entities
materials = model.materials
definitions = model.definitions
selection = model.selectionWichtig ist der Unterschied zwischen model.entities und model.active_entities. Ersteres enthält die Elemente auf der obersten Ebene des Modells. Hat der Benutzer eine Gruppe oder Komponente zur Bearbeitung geöffnet, gibt active_entities die Elemente des aktuellen Bearbeitungskontexts zurück. Ist kein Bearbeitungskontext geöffnet, liefert es dasselbe Ergebnis wie entities. Wenn Sie also nicht die oberste Modellebene, sondern den Inhalt bearbeiten möchten, an dem der Benutzer gerade arbeitet, müssen Sie die passende Sammlung wählen.
2. Die Auswahl effizient und sicher untersuchen
model.selection repräsentiert die aktuell ausgewählten Zeichnungselemente. Mit each über jedes Element der Auswahl zu iterieren ist effizienter, als die Indizes der Reihe nach aufzurufen. Gehen Sie außerdem nicht davon aus, dass die Reihenfolge der Auswahl der Reihenfolge entspricht, in der der Benutzer die Elemente ausgewählt hat: Laut Dokumentation ist die Reihenfolge der Elemente nicht festgelegt.
selection = Sketchup.active_model.selection
puts "Anzahl ausgewählter Elemente: #{selection.length}"
selection.each do |element|
puts element.typename
endWenn sich ein Vorgang nur auf ein einzelnes Element bezieht, können Sie first verwenden. Ist die Auswahl leer, gibt diese Methode nil zurück. Mit empty? prüfen Sie, ob Elemente ausgewählt sind, und mit single_object?, ob die Auswahl als einzelnes Objekt behandelt werden kann. Um zu prüfen, ob ein Element ausgewählt ist, steht include? zur Verfügung.
Wenn Sie während der Iteration Elemente aus derselben Sammlung löschen, können sich deren Größe und Indizes ändern. Dadurch können einzelne Elemente übersprungen werden. Als sichere Methode empfiehlt die Dokumentation, die zu löschenden Elemente zunächst in ein Array zu kopieren und anschließend mit dieser Kopie zu arbeiten. Auch der Zugriff über Indizes wie selection[0] ist keine effiziente Wahl, wenn Sie jedes Element untersuchen möchten. Zum Entfernen von Elementen aus der Auswahl oder zum Leeren der Auswahl können Sie die Methoden remove und clear verwenden.
3. Geometrie im richtigen Zeichenkontext erstellen
Neue Elemente wie Linien oder Flächen werden der ausgewählten Entities-Sammlung hinzugefügt. add_line erstellt beispielsweise eine Kante zwischen zwei Punkten, add_face fügt eine Fläche hinzu und add_group erstellt eine neue Gruppe. Für Vorgänge auf der obersten Ebene verwenden Sie model.entities; für die Arbeit im Kontext einer geöffneten Gruppe oder Komponente eignet sich model.active_entities. So wird die erzeugte Geometrie dem vorgesehenen Bereich des Modells hinzugefügt.
Besteht ein Vorgang aus mehreren Modelländerungen, hilft SketchUps Operationsmechanismus dabei, diese als rückgängig machbaren Vorgang zu erfassen. start_operation startet einen neuen Vorgang, commit_operation schließt ihn ab und abort_operation kann einen begonnenen Vorgang im Fehlerfall abbrechen. Verwenden Sie diese Methoden, um mehrere zusammengehörige Änderungen in einem Automatisierungsablauf konsistent zu verwalten.
model = Sketchup.active_model
model.start_operation("Linie hinzufügen")
begin
model.active_entities.add_line([0, 0, 0], [500, 500, 0])
model.commit_operation
rescue
model.abort_operation
raise
endLaut Dokumentation wird abort_operation normalerweise im Fehlerbehandlungsblock aufgerufen. Bei transparenten (transparent) Operationen wird jedoch davon abgeraten, diese Methode zu verwenden: Das Abbrechen einer solchen Operation kann auch die vorherige Operation abbrechen, an die sie angehängt ist. Wenn Ihre Automatisierung mit transparenten Operationen arbeitet, sollten Sie die Fehlerbehandlung daher gesondert planen.
Wenn Sie viele Geometrieelemente erstellen, kommt auch Entities#build infrage. Die API-Dokumentation beschreibt diese Methode als Möglichkeit, ein EntitiesBuilder-Objekt für die gebündelte Erstellung von Geometrie mit Blick auf die Performance anzulegen. Aus den dokumentierten Informationen sollte jedoch weder ein bestimmter Geschwindigkeitsgewinn noch die Eignung für jeden Anwendungsfall abgeleitet werden.
4. Komponenteninstanzen von ihrer Definition lösen
Eine ComponentInstance verweist auf eine Komponentendefinition und auf die Transformation, die ihre Position im Modell festlegt. Dadurch kann dieselbe Definition mehrfach als Instanz im Modell verwendet werden. Mit definition können Sie beispielsweise die Definition einer Instanz abrufen, mit transformation ihre Positionstransformation untersuchen oder sie über definition= einer anderen Definition zuweisen.
Wenn nur eine Instanz unabhängig von den anderen bearbeitet werden soll, können Sie make_unique verwenden. Die Methode erstellt für diese Instanz eine Komponentendefinition, die von keiner anderen Instanz verwendet wird. Legen Sie vorher fest, ob die Änderung für alle gemeinsam genutzten Instanzen oder nur für die ausgewählte Instanz gelten soll. Andernfalls kann das Ergebnis im Modell von der beabsichtigten Reichweite der Änderung abweichen. Die Dokumentation führt auch explode auf, eine Methode, die eine Komponente in einzelne Zeichnungselemente umwandelt. In Workflows, in denen sie als Komponenteninstanz erhalten bleiben soll, sollte diese Methode jedoch nicht verwendet werden.
Einsatz in Architektur- und Visualisierungsworkflows
Diese Methoden bilden eine Grundlage für Architekten, Innenarchitekten und SketchUp-Plugin-Entwickler, die wiederkehrende Modellprüfungen oder geometrische Bearbeitungen automatisieren möchten. So können Sie etwa Elemente im aktiven Bearbeitungskontext untersuchen, ausgewählte Objekte gemeinsam auswerten oder wiederkehrende Geometrie als einen Vorgang erstellen. Der Nutzen dieses Ansatzes hängt davon ab, dass klar festgelegt ist, in welchem Modellbereich die Automatisierung arbeitet und welche Instanzen von einer Änderung an einer Komponente betroffen sind.
Die Dokumentation nennt für diese API-Methoden keine besonderen Hardwareanforderungen oder Lizenzbedingungen; solche Anforderungen sollten daher nicht unterstellt werden. Prüfen Sie vor der Umsetzung die Hinweise zu den verwendeten SketchUp-Versionen, insbesondere bei Funktionen, die mit einer neueren Versionsangabe gekennzeichnet sind. Wenn Sie in großen Modellen Geometrie gebündelt erstellen, sollten Sie bei der Bewertung von Entities#build auch planen, wie sich der bestehende Workflow mit rückgängig machbaren Vorgängen verwalten lässt.
Häufige Fehler
Immer
model.entitiesverwenden: Wenn eine Gruppe oder Komponente geöffnet ist, kannactive_entitiesder richtige Kontext sein.Annehmen, dass die Auswahlreihenfolge der Klickreihenfolge des Benutzers entspricht: Laut API-Dokumentation ist diese Reihenfolge nicht garantiert.
Während
eachElemente aus derselben Sammlung löschen: Erstellen Sie zuerst mitto_aeine Kopie, damit keine Elemente übersprungen werden.Beim Bearbeiten einer Komponenteninstanz übersehen, dass die Definition gemeinsam genutzt wird: Soll nur eine Instanz unabhängig sein, sollten Sie
make_uniquein Betracht ziehen.Eine transparente Operation mit
abort_operationabbrechen: Die Dokumentation warnt, dass dadurch auch die Operation abgebrochen werden kann, an die sie angehängt ist.
Quellen
3 QuellenQuelltexte werden nicht neu veröffentlicht; kurze Zitate sind gekennzeichnet, der Rest ist eigene Zusammenfassung und Einordnung.
Für kleine Architektur- und Visualisierungsbüros in der Türkei liegt der praktische Nutzen dieser API darin, häufig wiederholte Modellprüfungen und Bearbeitungen in einen automatisierten Workflow zu überführen. Wer insbesondere Auswahl, aktiven Bearbeitungskontext und Komponentendefinitionen korrekt verwaltet, kann manuelle Schritte reduzieren und zugleich das Risiko unerwarteter Modelländerungen senken.
Die Einstiegshürde hängt hier weniger von neuer Hardware als vielmehr von Ruby-API-Kenntnissen und der Integration in bestehende Plugin-Workflows ab; die Quellen nennen keine bestimmten Hardware- oder Lizenzbedingungen. Büros sollten zunächst in einem kleinen Modell testen, ob sich Vorgänge rückgängig machen lassen, wie Komponenteninstanzen gemeinsam genutzt werden und ob die Methoden mit ihrer SketchUp-Version kompatibel sind.
Häufige Fragen
Wie greift man in der SketchUp Ruby API auf das aktive Modell zu?
Mit `Sketchup.active_model` greifen Sie auf das geöffnete Modell zu. Über das Model-Objekt können Sie auf Sammlungen wie Geometrie, Auswahl, Materialien und Komponentendefinitionen zugreifen.
Was ist der Unterschied zwischen entities und active_entities in der SketchUp Ruby API?
`entities` gibt die Elemente auf der obersten Modellebene zurück. `active_entities` liefert die Elemente des geöffneten Gruppen- oder Komponentenbearbeitungskontexts. Ist kein solcher Kontext geöffnet, entspricht das Ergebnis dem von `entities`.
Wie lässt sich eine SketchUp-Komponenteninstanz von anderen Instanzen lösen?
`ComponentInstance#make_unique` erstellt eine Komponentendefinition, die von keiner anderen Instanz gemeinsam genutzt wird. So kann die Änderung nur auf die unabhängig gemachte Instanz angewendet werden.



