Коротко
- В Revit категория, Family, FamilySymbol и FamilyInstance обозначают разные уровни классификации.
- С помощью API помещение можно создать на определённом этаже и в заданном месте.
- Границы помещения зависят от замкнутой области и параметра Room Bounding у окружающих элементов.
- В начальном курсе Autodesk University рассматриваются RevitPythonShell, Revit Lookup и pyRevit.
Чему вы научитесь в этом руководстве?
Руководство предназначено для тех, кто хочет разобраться в категориях и помещениях в Revit API и правильно интерпретировать примеры из документации Autodesk для разработчиков. Сначала рассмотрим, как элемент Revit классифицируется по категории, семейству, типу и экземпляру. Затем объясним два способа создания помещений через API и условия, которые необходимо проверить при чтении их границ.
Цель материала — не предоставить готовое расширение, которое сразу заработает в любом проекте. Примеры кода показывают, с какими объектами и условиями проекта работает API. Примеры в источниках приведены на C#, поэтому вставлять их в инструмент для Python как Python-код не следует.
Требования и область рассмотрения
В начальном курсе Autodesk University используются Revit, RevitPythonShell, Revit Lookup и pyRevit. Для обучения необходимы базовые знания Revit и начальный уровень владения Python. Однако это не означает, что примеры API, используемые ниже, написаны на Python: фрагменты кода о помещениях и категориях в документации Autodesk приведены на C#.
Одна из рассматриваемых страниц документации для разработчиков относится к Revit 2018, другая — к документации Revit 2024. В источниках не поясняется совместимость этих примеров с разными версиями Revit. Поэтому перед использованием примера в реальном проекте проверьте документацию API для целевой версии. Требования к учётной записи, актуальные версии инструментов и условия их лицензирования в указанных источниках не описаны.
1. Разберитесь в категориях и структуре семейств
Категория определяет общий тип элемента и то, как Revit с ним работает. Стены, двери и помещения — примеры разных категорий. Категории связаны с такими функциями, как создание спецификаций, редактирование параметров, управление видимостью и графическим отображением.
Структура семейств устроена более детально. Family представляет семейство целиком, FamilySymbol — определённый тип этого семейства, а FamilyInstance — отдельный экземпляр, размещённый в проекте. Например, семейство двери может включать разные типы, а каждая установленная в проекте дверь считается экземпляром. В API это различие важно, чтобы не путать общую категорию элемента с его конкретным типом.
Пример Autodesk для категорий показывает, как обратиться к коллекции категорий открытого документа и выбрать встроенную категорию. В документации также предупреждается, что названия категорий могут различаться в зависимости от языка интерфейса Revit. Чтобы не зависеть от языковых различий, рассмотрите использование встроенных определений категорий, например BuiltInCategory, вместо обращения к названию категории как к текстовой строке.
2. Выберите способ создания помещения
В документации API описаны два сценария создания помещения. В первом оно создаётся с указанием этажа и местоположения. В примере положение задаётся значением типа UV, а затем проверяется, успешно ли выполнено создание. Основная идея здесь в том, что вызову для создания помещения нужны не только данные самого помещения, но и сведения о том, на каком этаже и где оно должно находиться.
Во втором сценарии помещение сначала создаётся в спецификации помещений с привязкой к фазе проекта, а затем добавляется в плановый контур. Важно, чтобы помещение, добавляемое на план, находилось только в спецификации помещений и ещё не было размещено ни на одном виде плана. Плановый контур определяется через топологию плана соответствующего этажа. При успешном размещении на виде, в котором находится плановый контур, появляется модельное помещение с тем же именем и номером.
Перед применением этих подходов определите, какой результат вам нужен: создать помещение в заданной точке или разместить в плановом контуре помещение, которое пока числится в спецификации. Если во втором сценарии пропустить условие о наличии помещения в спецификации, операция может не сработать с ожидаемыми входными данными.
3. Изучите границы помещений и их обновление
Границы помещений зависят от элементов модели, образующих замкнутую область. Среди примеров таких элементов в документации Autodesk перечислены стены, линии модели, колонны и крыши. Для чтения сегментов границы используется метод SpatialElement.GetBoundarySegments(). Возвращаемые данные могут содержать одну или несколько областей и сегменты каждой из них в виде вложенных списков.
Данные о границах могут возвращаться не во всех случаях. Если помещение не находится в замкнутой области или существует только в спецификации помещений, метод может вернуть null. Поэтому, если результат не получен, проверьте не только вызов API, но и то, образует ли модель замкнутое помещение и размещено ли оно на виде плана.
Для включения стен, колонн, крыш и других элементов в границу помещения важен параметр Room Bounding. Границы также могут формироваться линиями разделения помещений. Если через API добавить стену или другой элемент, граница помещения может измениться — поэтому не считайте данные о границах, полученные до изменений, актуальными после них. В примере Autodesk сначала завершается создание элемента внутри transaction, а затем границы считываются повторно.
Чтобы переместить помещение, его также можно сначала удалить с текущего места. В документации поясняется, что метод Room.Unplace() снимает помещение с размещения, но оно остаётся доступным в проекте. Это требует понимания разницы между удалением объекта из проекта и изменением его размещения.
4. Влияние на архитектурные процессы и визуализацию
Понимание границ помещений и связей категорий может быть полезно архитектурным и интерьерным командам, которые работают с данными помещений, классифицируют элементы модели или рассматривают автоматизацию повторяющихся операций. Поскольку границы помещений зависят от окружающих элементов модели и их настроек, перед автоматизацией необходимо убедиться, что эти связи в модели заданы правильно.
В этих источниках не описываются непосредственно настройки рендера или визуализации. Тем не менее согласованность модели важна в BIM-процессах, использующих данные о помещениях и категориях. Перед началом работы проверьте версию Revit, состояние размещения помещения, настройки Room Bounding у соответствующих элементов и фазу проекта. Небольшая тестовая модель подойдёт студентам для наблюдения за тем, как данные о границах меняются при изменении стен и других окружающих элементов.
Частые ошибки
Считать, что названия категорий одинаковы во всех языковых версиях Revit. Чтобы избежать языковых различий, Autodesk рекомендует использовать встроенные определения категорий.
Ожидать сегменты границ, хотя помещение не находится в замкнутой области. Согласно документации, в этом случае метод может вернуть null.
Разместить в виде плана помещение, которое нужно добавить в плановый контур. Оно должно находиться только в спецификации помещений.
Не проверять параметр Room Bounding у окружающих элементов. Он определяет, учитывается ли элемент в границе помещения.
Продолжать использовать данные о границах, полученные до создания нового элемента модели. После завершения изменений считайте границы заново.
Принимать примеры на C# за код Python. В источниках упоминаются инструменты для Python, но примеры API для помещений и категорий приведены на C#.
Что делать дальше
Сначала изучите объяснения Autodesk о категориях и на существующем проекте разберитесь в различиях между категорией, семейством, типом и экземпляром. Затем сравните сценарии создания помещений в тестовом документе: создание с указанием местоположения и размещение в плановом контуре из спецификации. На каждом шаге отмечайте, на каком виде находится помещение.
В завершение измените элементы вокруг замкнутой области помещения и снова проверьте данные о границах. Это упражнение поможет не рассматривать возвращаемое API значение в отрыве от состояния модели. При переходе к более сложной автоматизации также рассмотрите фильтры элементов, транзакции и вопросы пользовательского интерфейса, затронутые в начальном курсе Autodesk University.
Источники и лицензия
Руководство подготовлено своими словами на основе тем о помещениях в документации Autodesk Revit API для разработчиков (K1), классификации категорий и семейств (K2), а также начального курса Autodesk University по Revit API (K4). Для источников указан статус «свободно»; поскольку в предоставленных текстах не приводится конкретное название лицензии, здесь отдельный тип лицензии не указывается.
Источники
Источников: 3Тексты источников не перепечатываются; короткие цитаты отмечены, остальное — наш пересказ и комментарий.
Категории и границы помещений — хорошая отправная точка для офисов, которые хотят связать данные модели Revit с автоматизацией. Практическая польза прежде всего в том, чтобы научиться оценивать результат вызова API не только по коду, но и с учётом состояния помещения в спецификации или на плане, а также окружающих элементов.
Для офисов и студентов в Турции этот подход стоит сначала проверить на небольшом тестовом проекте и только затем переносить в рабочую модель. Поскольку в источниках не указаны совместимость актуальных версий инструментов, стоимость лицензий и требования к оборудованию, перед принятием инвестиционных решений эти сведения необходимо проверить отдельно. Из этих документов также нельзя сделать выводы о производительности рендера.
Частые вопросы
Как прочитать границы помещений через Revit API?
В документации Autodesk указано, что сегменты границ можно получить с помощью метода SpatialElement.GetBoundarySegments(). Если помещение не находится в замкнутой области или существует только в спецификации, метод может вернуть null.
Как добавить помещение из спецификации на план через Revit API?
Согласно документации, сначала помещение создаётся в спецификации помещений с привязкой к фазе проекта, а затем размещается на плане с помощью PlanCircuit. Оно должно находиться только в спецификации и ещё не быть размещённым ни на одном виде плана.
Зависят ли названия категорий в Revit API от языка?
Autodesk указывает, что значение Category.Name может зависеть от языка Revit. Чтобы избежать языковых различий, рекомендуется использовать BuiltInCategory.
