SketchUp-Komponenten: Leitfaden zu ComponentInstance und Definition

Die SketchUp-Ruby-API-Dokumentation erklärt, wie Komponenteninstanzen in einem Modell dargestellt und die zugehörigen Definitionen verwaltet werden. ComponentInstance steht für eine im Modell platzierte Komponenteninstanz; ComponentDefinition bezeichnet die Definition, auf der diese Instanz basiert. Ihre Position im Modell wird außerdem durch eine Transformation festgelegt. Diese Unterscheidung hilft dabei, gemeinsame Änderungen an wiederverwendeten Objekten von Änderungen abzugrenzen, die nur eine einzelne Instanz betreffen.

Dieser Leitfaden stützt sich auf die Dokumentation der SketchUp Ruby API zu ComponentInstance, DefinitionList und Model. Die Versionshinweise zu den einzelnen Methoden unterscheiden sich; wo eine bestimmte Versionsangabe vorliegt, wird die entsprechende Grenze gesondert genannt.

1. Das Verhältnis zwischen Instanz und Komponentendefinition verstehen

1. Betrachten Sie die Komponenteninstanz im Modell getrennt von ihrer Definition. Eine ComponentInstance verweist auf ein ComponentDefinition-Objekt und enthält über eine Transformation Angaben zu ihrer Position. So kann dieselbe Definition von mehreren platzierten Instanzen verwendet werden. Prüfen Sie daher vor der Bearbeitung einer Instanz, mit welcher Definition sie verknüpft ist.

2. In der Ruby API liefert Sketchup.active_model das aktive Modell. Die Methode definitions des Model-Objekts greift auf die DefinitionList-Sammlung mit den ComponentDefinition-Objekten des Modells zu. Die Methode definition einer Instanz gibt dagegen direkt die Definition zurück, mit der diese Instanz verknüpft ist. Die Definitionen des gesamten Modells zu untersuchen und die Definition einer bestimmten Instanz zu ermitteln, sind somit unterschiedliche Vorgänge.

3. Wenn Änderungen an anderen Instanzen derselben Definition vermieden werden sollen, sollten Sie vor der Bearbeitung der einzelnen Instanz die Methode make_unique in Betracht ziehen. Laut Dokumentation erstellt sie für diese Instanz eine neue Definition, die von den übrigen Instanzen nicht verwendet wird. Das ist hilfreich, wenn nur ein einzelnes Objekt aus einer Gruppe mehrfach verwendeter Möbel, Türen oder Ausstattungselemente geändert werden soll.

2. Instanzen mit der Ruby API untersuchen und trennen

Das folgende Beispiel sucht im aktiven Bearbeitungskontext des aktiven Modells nach der ersten ComponentInstance. Wird eine Instanz gefunden, gibt es den Namen der verknüpften Definition aus und erstellt anschließend mit make_unique eine eigenständige Definition für diese Instanz. Der Code durchsucht nicht die gesamte Definitionsliste des Modells; den Namen bezieht er über die Methode definition der ausgewählten Instanz.

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

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

1. Prüfen Sie vor der Ausführung in Ihrem Modell, welche Komponente ausgewählt ist oder sich im aktiven Bearbeitungskontext befindet. Der Code ruft die erste ComponentInstance ab; er wählt keine bestimmte Komponente anhand ihres Namens aus. Gibt es mehrere Komponenten, sollten Sie daher die Ausgabe und die Zielinstanz überprüfen. Der Aufruf von make_unique zeigt nicht nur Informationen an, sondern erstellt im Modell eine eigenständige Definition.

2. Die verknüpfte Definition zu ändern und die Position der Instanz zu ändern, sind zwei unterschiedliche Aufgaben. Die Methode definition= von ComponentInstance weist eine andere Definition zu; laut Dokumentation bleibt dabei die aktuelle Transformation der Instanz erhalten. Mit transformation und transformation= lässt sich die Transformation auslesen beziehungsweise festlegen. transform! wendet eine Geom::Transformation an; move! legt die Transformation auf ähnliche Weise fest, speichert den Vorgang jedoch nicht im Undo-Verlauf. Berücksichtigen Sie diesen Unterschied bei der Planung der Bearbeitungs- und Rückgängig-Abläufe Ihres Plugins.

3. Geometrie und Definitionssammlungen sorgfältig bearbeiten

1. Die Methode explode wandelt eine Komponenteninstanz in einzelne Zeichnungselemente um. Bei Erfolg kann sie ein Array von Elementen zurückgeben, bei einem Fehlschlag false. Wenn die Komponentenstruktur erhalten bleiben soll, sollten Sie vor der Verwendung prüfen, welche Auswirkungen der Vorgang auf das Modell hat. Die Dokumentation führt außerdem geometrische Operationen wie intersect, outer_shell, split, subtract, trim und union auf; einige davon sind für die Arbeit mit manifold Volumenkörpern vorgesehen. Gehen Sie daher nicht davon aus, dass sie bei jeder Komponente dasselbe Ergebnis liefern.

2. trim berechnet die Differenz zwischen zwei manifold Volumenkörpern zerstörungsfrei; subtract ist eine weitere aufgeführte Methode für Differenzoperationen. Die API-Dokumentation weist außerdem darauf hin, dass intersect in SketchUp Make nicht verfügbar ist. Die Methode manifold? von ComponentInstance ist als veraltet gekennzeichnet; laut Dokumentation sollte ComponentDefinition#manifold? verwendet werden, um den manifold-Status der Definition zu prüfen. Diese Hinweise zeigen, dass vor geometrischen Operationen die Methodenbeschreibung und der Objekttyp geprüft werden sollten.

3. DefinitionList enthält Methoden, um Definitionen nach Index, Name oder GUID zu finden, neue Definitionen hinzuzufügen, Komponenten aus Dateien zu laden und nicht verwendete Definitionen zu bereinigen. purge_unused entfernt nicht verwendete Definitionen. Vermeiden Sie es, beim Durchlaufen der Sammlung mit each Elemente aus derselben Sammlung zu löschen: Die Dokumentation warnt, dass sich Elementanzahl und Indizes ändern können, wodurch einige Definitionen übersprungen werden könnten. Wenn Elemente gelöscht werden müssen, empfiehlt die Dokumentation, zunächst eine Array-Kopie der Sammlung anzulegen und diese zu bearbeiten.

4. Versionskompatibilität und Dateisicherheit prüfen

1. Die Methode load in DefinitionList dient dazu, eine SketchUp-Komponentendatei zu laden. Laut Dokumentation gibt es ab SketchUp 2021.0 die Option allow_newer, mit der Modelle geladen werden können, die in einer neueren Version gespeichert wurden. Beim Laden können jedoch Informationen ausgelassen werden; die API-Dokumentation warnt davor, die aus einem neueren Modell geladene Datei zu überschreiben. Die Quelldatei zu schützen, sollte daher Teil des Workflows sein.

2. Für das erneute Laden einer Komponente über denselben Dateipfad gibt es ebenfalls einen Versionshinweis. Vor SketchUp 2023.0 konnte der Ladeaufruf eine bereits vorhandene Komponente zurückgeben, statt neue Inhalte zu laden, wenn im Modell eine andere Komponente mit demselben Pfad verknüpft war. Wenn die Datei offenbar nicht aktualisiert wurde, prüfen Sie die verwendete SketchUp-Version und den Dateipfad; berücksichtigen Sie die in der Quelldokumentation genannten Versionsgrenzen bei der Kompatibilität Ihres Plugin-Codes.

Auswirkungen auf Workflows in Architektur, Innenarchitektur und Visualisierung

Für Architektur- und Innenarchitekturbüros, die wiederkehrende Möbel, Türen und Ausstattungselemente verwenden, erleichtert die Unterscheidung zwischen Instanz und Definition, den Umfang von Änderungen im Modell zu verstehen. Wenn gemeinsame Änderungen über eine geteilte Definition vorgenommen werden sollen, ist die Komponentenverknüpfung hilfreich. Soll dagegen nur eine einzelne Instanz abweichen, bietet die API dafür die Methode make_unique. Diese Unterscheidung kann Teams dabei helfen, nachzuvollziehen, welche Elemente sich gemeinsam ändern.

Auch für Visualisierungsteams und Plugin-Entwickler ist entscheidend, sicherzustellen, dass die richtige Instanz und die richtige Definition ausgewählt wurden. In den Quellen werden keine bestimmten Hardwareanforderungen, Leistungsmessungen oder Lizenzbedingungen genannt. Konkret zu beachten ist, ob die verwendete SketchUp-Version die jeweilige Methode unterstützt und ob beim Laden von Dateien aus neueren Versionen die Quelldatei geschützt wird.

Häufige Fehler

• Die gemeinsam genutzte Definition einer Instanz bearbeiten, ohne zu berücksichtigen, dass sich dadurch auch andere Instanzen ändern können.

• Vergessen, dass der Code die erste ComponentInstance findet, und davon ausgehen, dass ein bestimmtes Objekt ausgewählt wird.

• Die Zuweisung einer Definition mit der Änderung der Positionstransformation verwechseln.

• Geometrische Methoden mit Manifold-Bedingungen so verwenden, als würden sie bei jeder Komponente funktionieren.

• Beim Durchlaufen einer DefinitionList Elemente aus derselben Sammlung löschen.

• Nach dem Laden eines neueren Modells den Hinweis ignorieren, die Quelldatei nicht zu überschreiben.