Räume mit der Revit API erstellen und Begrenzungen untersuchen: Einstieg

Was lernen Sie in diesem Leitfaden?

Dieser Leitfaden richtet sich an alle, die Kategorien und Räume in der Revit API verstehen und Beispiele aus der Autodesk-Entwicklerdokumentation im richtigen Kontext bewerten möchten. Zunächst betrachten wir, wie ein Revit-Element als Kategorie, Familie, Typ und Exemplar klassifiziert wird. Anschließend erläutern wir zwei Wege, Räume über die API zu erstellen, und die Bedingungen, die beim Auslesen von Raumbegrenzungen zu prüfen sind.

Ziel ist es nicht, ein fertiges Add-in bereitzustellen, das sich direkt in jedem Projekt einsetzen lässt. Die Codebeispiele zeigen, mit welchen Objekten und Projektbedingungen die API arbeitet. Die Beispiele in den Quellen sind in C# verfasst; sie einfach so in ein Python-Tool einzufügen, als wären sie Python-Code, wäre daher nicht richtig.

Voraussetzungen und Umfang

Der Einsteigerkurs der Autodesk University verwendet Revit, RevitPythonShell, Revit Lookup und pyRevit. Als Voraussetzungen werden grundlegende Revit-Kenntnisse und Python-Kenntnisse auf Einstiegsniveau genannt. Das bedeutet nicht, dass auch die API-Beispiele in den folgenden Erläuterungen Python-Code sind: Die Codeausschnitte in der Autodesk-Dokumentation zu Räumen und Kategorien sind in C# verfasst.

Eine der herangezogenen Entwicklerdokumentationen bezieht sich auf Revit 2018, eine andere ist eine Dokumentationsseite für Revit 2024. Die Quellen erläutern nicht, ob die Beispiele mit unterschiedlichen Revit-Versionen kompatibel sind. Prüfen Sie daher vor dem Einsatz eines Beispiels in einem echten Projekt die API-Dokumentation für die Zielversion. Anforderungen an ein Konto, aktuelle Tool-Versionen und Lizenzbedingungen der Tools werden in den angegebenen Quellen nicht erläutert.

1. Kategorien und Familienstruktur unterscheiden

Eine Kategorie klassifiziert, welcher Art ein Element grundsätzlich ist und wie Revit damit umgeht. Wände, Türen und Räume sind Beispiele für unterschiedliche Kategorien. Kategorien stehen mit Funktionen wie dem Erstellen von Bauteillisten, dem Bearbeiten von Parametern sowie der Steuerung von Sichtbarkeit und grafischer Darstellung in Verbindung.

Die Familienstruktur ist detaillierter. Family bezeichnet die gesamte Familie, FamilySymbol einen bestimmten Typ dieser Familie und FamilyInstance ein einzelnes Exemplar, das im Projekt platziert wurde. Eine Türfamilie kann beispielsweise verschiedene Typen enthalten; jede im Projekt verwendete Türplatzierung gilt wiederum als eigenes Exemplar. Diese Unterscheidung ist in der API wichtig, damit die allgemeine Kategorie eines Elements nicht mit einem bestimmten Typ verwechselt wird.

Das Kategoriebeispiel von Autodesk zeigt, wie auf die Kategoriesammlung des geöffneten Dokuments zugegriffen und eine integrierte Kategorie ausgewählt wird. Die Dokumentation weist außerdem darauf hin, dass die Namen von Kategorien je nach Sprache der Revit-Oberfläche variieren können. Um unabhängig von Sprachunterschieden zu bleiben, sollten Sie statt einer Abhängigkeit von Namenszeichenfolgen integrierte Kategoriebezeichner wie BuiltInCategory in Betracht ziehen.

2. Den passenden Weg zur Raumerstellung wählen

Die API-Dokumentation beschreibt zwei unterschiedliche Szenarien zum Erstellen eines Raums. Im ersten wird ein Raum anhand einer Ebene und einer Position erstellt. Das Beispiel gibt die Position mit einem Wert des Typs UV an und prüft, ob das Ergebnis der Erstellung gültig ist. Entscheidend ist dabei, dass der Aufruf zur Raumerstellung nicht nur das Raumobjekt voraussetzt, sondern auch Angaben dazu, auf welcher Ebene und an welcher Position es liegen soll.

Im zweiten Szenario wird zunächst ein Raum mit einer Projektphase verknüpft und in einer Raumliste erstellt; anschließend wird er einem PlanCircuit hinzugefügt. Dabei gilt die wichtige Bedingung, dass der hinzuzufügende Eintrag nur in der Raumliste vorhanden und noch keiner Planansicht zugewiesen sein darf. Der PlanCircuit wird über die Plan-Topologie der betreffenden Ebene ermittelt. Bei erfolgreicher Platzierung entsteht die Modellrauminstanz mit demselben Namen und derselben Nummer in der Ansicht, in der sich der PlanCircuit befindet.

Legen Sie vor der Umsetzung fest, welches Ergebnis Sie benötigen: einen Raum an einem bestimmten Punkt erstellen oder einen noch nicht platzierten Raum aus der Liste einem PlanCircuit zuweisen? Wird beim zweiten Ablauf die Bedingung übergangen, dass der Raum in der Liste vorhanden sein muss, kann der Vorgang mit den erwarteten Eingaben möglicherweise nicht funktionieren.

3. Raumbegrenzungen und Aktualisierungen untersuchen

Raumbegrenzungen hängen von den Modellelementen ab, die einen geschlossenen Bereich bilden. In der Autodesk-Dokumentation werden unter anderem Wände, Modelllinien, Stützen und Dächer als Elemente genannt, die mit Begrenzungen in Verbindung stehen. Zum Auslesen der Begrenzungssegmente wird die Methode SpatialElement.GetBoundarySegments() verwendet. Die zurückgegebenen Daten können eine oder mehrere Regionen und die Segmente jeder Region als verschachtelte Listen enthalten.

Nicht in jedem Fall werden Begrenzungsdaten zurückgegeben. Liegt der Raum nicht in einem geschlossenen Bereich oder ist er nur in der Raumliste vorhanden, kann die Methode null zurückgeben. Wenn keine Ergebnisse vorliegen, prüfen Sie daher nicht nur den API-Aufruf, sondern auch, ob das Modell tatsächlich einen geschlossenen Raum bildet und ob der Raum in einer Planansicht platziert ist.

Die Einstellung Room Bounding ist dafür relevant, ob Elemente wie Wände, Stützen und Dächer zur Raumbegrenzung beitragen. Auch Raumtrennlinien können Begrenzungen erzeugen. Wird über die API ein Element wie eine Wand hinzugefügt, kann sich die Raumbegrenzung ändern. Betrachten Sie daher Begrenzungsdaten, die vor der Änderung ermittelt wurden, danach nicht als aktuell. Das Autodesk-Beispiel zeigt, wie das Erstellen eines Elements innerhalb einer Transaktion abgeschlossen und anschließend die Begrenzung erneut ausgelesen wird.

Um einen Raum zu verschieben, kann er zunächst aus seiner aktuellen Position entfernt werden. Die Dokumentation erklärt, dass sich ein Raum mit der Methode Room.Unplace() aus seiner Position lösen lässt, aber im Projekt verfügbar bleibt. Dafür muss man den Unterschied zwischen dem Löschen des Objekts aus dem Projekt und dem Ändern seiner Platzierung verstehen.

4. Auswirkungen auf Architektur- und Visualisierungs-Workflows

Das Verständnis von Raumbegrenzungen und Kategorienbeziehungen kann Architektur- und Innenarchitekturbüros helfen, die mit Raumdaten arbeiten, Modellelemente klassifizieren oder wiederkehrende Vorgänge automatisieren möchten. Da Raumbegrenzungen von den umgebenden Modellelementen und deren Einstellungen abhängen, sollte vor Beginn einer Automatisierung geprüft werden, ob das Modell diese Beziehungen korrekt abbildet.

Diese Quellen beschreiben keine direkten Render- oder Visualisierungseinstellungen. In BIM-Prozessen, die mit Raum- und Kategoriedaten arbeiten, ist ein konsistentes Modell jedoch wichtig. Prüfen Sie vor der Umsetzung die verwendete Revit-Version, den Platzierungsstatus des Raums, die betreffenden Einstellungen für Room Bounding und die Projektphase. Ein kleines Testmodell ist für Studierende ein guter Ausgangspunkt, um zu beobachten, wie sich Änderungen an einer Wand oder einem anderen umgebenden Element auf die Begrenzungsdaten auswirken.

Häufige Fehler

• Davon ausgehen, dass Kategorienamen in allen Revit-Sprachen gleich sind. Autodesk empfiehlt, integrierte Kategoriebezeichner zu verwenden, um Sprachunterschiede zu vermeiden.

• Begrenzungssegmente erwarten, obwohl der Raum nicht in einem geschlossenen Bereich liegt. Laut Dokumentation kann die Methode in diesem Fall null zurückgeben.

• Den Raum, der einem PlanCircuit hinzugefügt werden soll, zuvor in einer Planansicht platzieren. Die Eingabe darf nur in der Raumliste vorhanden sein.

• Die Einstellung Room Bounding für umgebende Elemente übersehen. Sie bestimmt, ob ein Element zur Raumbegrenzung beiträgt.

• Nach dem Erstellen eines neuen Modellelements weiterhin alte Begrenzungsdaten verwenden. Lesen Sie die Begrenzungsinformationen nach Abschluss der Änderung erneut aus.

• C#-Beispiele als Python-Code behandeln. Die Quellen erwähnen zwar Python-Tools, die API-Beispiele zu Räumen und Kategorien sind jedoch in C# verfasst.

Nächste Schritte

Lesen Sie zunächst die Erläuterungen von Autodesk zu Kategorien und beobachten Sie in einem bestehenden Projekt den Unterschied zwischen Kategorie, Familie, Typ und Exemplar. Vergleichen Sie anschließend in einem Testdokument die Szenarien zur Raumerstellung: Erstellen anhand einer Position und Platzieren aus der Raumliste in einem PlanCircuit. Notieren Sie bei jedem Schritt, in welcher Ansicht sich der Raum befindet.

Prüfen Sie zuletzt die Begrenzungsdaten erneut, nachdem Sie Elemente verändert haben, die einen geschlossenen Raumbereich umgeben. So lernen Sie, den Rückgabewert der API nicht losgelöst vom Zustand des Modells zu betrachten. Wenn Sie umfassendere Automatisierungen angehen, sollten Sie auch die Themen Elementfilter, Transaktionen und Benutzeroberfläche aus dem Einsteigerkurs der Autodesk University berücksichtigen.

Quellen und Lizenz

Der Leitfaden wurde in eigenen Worten anhand der Autodesk Revit API-Entwicklerdokumentation zu Räumen (K1), Kategorien und Familienklassifizierungen (K2) sowie des Einsteigerkurses der Autodesk University zur Revit API (K4) erstellt. Die Quellen sind als lizenz=frei gekennzeichnet; da in den bereitgestellten Texten keine konkrete Lizenz genannt wird, wird hier keine bestimmte Lizenzart angegeben.