Разработчику

• 1: Обзор
• 2: Концепт
• 2.1: Параметры платформы
• 3: Начало работы
• 3.1: Установка
• 3.2: Настройка окружения
• 3.2.1: Необходимое ПО
• 3.2.2: Visual Studio
• 3.2.3: PyCharm
• 3.2.4: Плагины для Autodesk Revit
• 4: Уроки
• 4.1: Создание плагинов
• 4.1.1: Что такое pyRevit?
• 4.1.2: Что такое Bim4Everyone?
• 4.1.3: Разработка на C#
• 4.1.4: Разработка на python
• 4.1.5: OpenSource
• 5: Примеры
• 6: FAQ
• 7: Внеси свой вклад

1 - Обзор

О платформе

Вы можете использовать платформу Bim4Everyone для разработки собственных скриптов на python и C#, для реализации автоматизации собственных процессов проектирования в компании.

Основой платформы является pyRevit, в котором уже реализовано создание на основе структуры папок кнопок на ленте инструментов Autodesk Revit.

Платформа поддерживает Revit 2022, Revit 2023, Revit 2024.

Начало работы с платформой

Если вы здесь в первый раз, то будет полезно обратиться к руководству Начало работы, Уроки или Примеры по работе с платформой:

• Начало работ
• Уроки
• Примеры

Если вы не знакомы с работой pyRevit, рекомендуется обратиться к его документации:

• Разработчикам
• Python документация

Список библиотек, сайтов и утилит, облегчающих написание скриптов для платформы:

• dosymep.Revit
• dosymep.SimpleServices
• dosymep.Autodesk
• Ninject
• Revit API Docs
• RevitLookup

Концепции

Доступны в следующей статье: Концепции

2 - Концепт

В данном разделе описаны ключевые идеи, на основе которых реализованы классы и методы платформы. Изучив данный раздел, вы сможете применять весь функционал, заложенный в платформу, при разработке своих решений автоматизации, предлагая пользователям максимальное количество инструментов в кратчайшие сроки.

2.1 - Параметры платформы

Введение

В платформе реализован подход с настройкой параметров, которые используются в плагинах. Это позволяет:

• переносить в проект параметры, используемые платформой;
• централизованно редактировать параметры для всех плагинов в случае их изменения;
• выявлять проблемы при работе с параметрами (например, при несовпадении StorageType или при отсутствии параметров в проекте);
• предоставлять базовый функционал по работе с параметрами с уже встроенными проверками и доп функциями.

Для реализации данного подхода используется:

• ряд классов платформы, через которые производится копирование, настройка, хранение параметров в коде и т.п.
• файл Revit, как шаблон-хранилище, откуда переносятся параметры в проект в целевые проекты для последующего использования плагинами.

Классы, отвечающие за работу с параметрами платформы имеют следующую структуру наследования:

• RevitParam:
  • SharedParam - класс общего параметра Revit;
  • ProjectParam - класс параметра проекта Revit;
  • SystemParam - класс системного параметра Revit.
• RevitParamsConfig:
  • SharedParamsConfig - класс конфигурации общих параметров Revit (в нем хранятся общие параметры конфигурации по умолчанию);
  • ProjectParamsConfig - класс конфигурации параметров проекта Revit (в нем хранятся параметры проекта конфигурации по умолчанию);
  • SystemParamsConfig - класс конфигурации системных параметров Revit (в нем хранятся системные параметры конфигурации по умолчанию).

Файл-шаблон Revit

Файл-шаблон Revit используется для хранения и копирования параметров в проект при помощи методов платформы. Это сделано из-за того, что программно создавать параметры в проекте Revit сложно, поэтому проще их переносить из другого проекта.

Файл располагается по пути:
%appdata%\pyRevit\Extensions\BIM4Everyone.lib\dosymep_libs\libs<Revit version>\templates\project_parameters.rvt

Файл-шаблон можно открыть при помощи кнопки “Открыть шаблон параметров” на вкладке “Admin” платформы в Revit. Кнопка “Параметры проекта” на вкладке “Управление” позволяет увидеть перечень всех параметров, которые добавлены в платформу.

Конфигурации параметров платформы

Конфигурация параметров - это набор параметров, с которыми работают плагины платформы.

Конфигурация по умолчанию - конфигурация с параметрами платформы, которые прописаны в коде классов ProjectParamsConfig, SystemParamsConfig или SharedParamsConfig.

Загружаемая конфигурация - конфигурация с параметрами платформы, которые загружаются из стороннего файл в JSON-формате.

Загрузка параметров происходит в файле startup.py по пути: %appdata%\pyRevit\Extensions\01.BIM.extension

Параметры платформы

В платформе есть специальные классы расширения, которые содержат методы по работе с параметрами.

Использование параметров платформы

Если параметр имеется в конфигурации по умолчанию (прописан в ProjectParamsConfig, SystemParamsConfig или SharedParamsConfig), то его можно использовать при разработке плагина путем вызова свойства Instance. Например:

SharedParamsConfig.Instance.AlbumBlueprints - используем конфигурацию для общих параметров (SharedParamsConfig), поэтому запрос вернет экземпляр класса SharedParam, описывающий общий Revit-параметр, под названием ADSK_Комплект чертежей.

В случае, если работа ведется не с конфигурацией по умолчанию, то получить параметр можно обратившись к экземпляру конфигурации и указав в квадратных скобках имя параметра (или идентификатор, в зависимости от типа параметра)

Например:

SharedParamsConfig["ADSK_Комплект чертежей"]

Получение значения параметра

GetParamValue - метод, который возвращает значение параметра элемента. При использовании в формате:

• GetParamValue() вернет объект класса object (рекомендуется для использования при написании кода на Python);
• GetParamValue<string>() вернет объект класса string (или любой другой, какой будет указан; удобнее, когда известно какой тип содержится в параметре).

Пример:

string levelValue = element.GetParamValue<string>(SharedParamsConfig.Instance.Level)

При этом механика работы следующая:

1. Метод пытается получить значение параметра у элемента;
2. Если параметра нет, или значение параметра null или пустая строка, то он выбрасывает исключение.

GetParamValueOrDefault - метод, который возвращает значение параметра элемента, либо значение по умолчанию. При использовании в формате:

• GetParamValueOrDefault() вернет объект класса object (рекомендуется для использования при написании кода на Python);
• GetParamValueOrDefault<string>() вернет объект класса string (или любой другой, какой будет указан; удобнее, когда известно какой тип содержится в параметре).

Пример:

string levelValue = element.GetParamValueOrDefault<string>(SharedParamsConfig.Instance.Level)

При этом механика работы следующая:

1. Метод пытается получить значение параметра у элемента
2. Если параметра нет, или значение параметра null или пустая строка, то он возвращает значение по умолчанию (с учетом типа, если он был передан).

При этом если в аргументах метода указано значение по умолчанию, то в случае возникновения проблем будет возвращено не стандартное значение по умолчанию, а то, которое было указано.

Пример:

string levelValue = element.GetParamValueOrDefault<string>(SharedParamsConfig.Instance.Level, "Произошла ошибка!")

Также в платформе присутствуют методы для работы со значениями параметров, в случае, когда параметры не принадлежат платформе - GetSharedParamValue (и аналоги) и GetProjectParamValue (и аналоги).

Проверка наличия параметра

IsExistsParam - метод, который проверяет, есть ли параметр у элемента. Возвращает true, если есть. При этом проверка производится через ParameterBindings документа.

Пример:

element.IsExistsParam(SharedParamsConfig.Instance.Level)

Проверка наличия значения параметра

IsExistsParamValue - метод, который проверяет, содержит ли параметр элемента значение. Возвращает true, если содержит. При этом проверка имеют следующую механику:

1. Проверяется, что у элемента есть параметр;
2. Проверяется, что HasValue параметра true;
3. Проверяется, что в значение параметра не равно null или пустой строке.

Пример:

element.IsExistsParamValue(SharedParamsConfig.Instance.Level)

Загрузка параметров в проект Revit

Для использования параметра плагином может потребоваться сначала загрузить параметр в проект. Этот процесс реализуется благодаря файлу Revit, используемому как шаблон, в котором хранятся параметры платформы. Для копирования и настройки параметров в проекте Revit предназначен класс ProjectParameters.
Методика копирования параметров в нужный проект:

1. На классе ProjectParameters вызвать метод Create и получить экземпляр класса ProjectParameters нужного приложения;
2. Вызвать на нем метод SetupRevitParam, чтобы скопировать один параметр в нужный проект;
3. Или вызвать SetupRevitParams, чтобы скопировать несколько параметров в нужный проект;
4. После этого платформа найдет указанный параметр в Revit-шаблоне, и произведет копирование в нужный Revit проект.

При этом механизм копирования параметров работает следующим образом:

1. Сначала производится синхронизация параметров, т.е. в случае если в целевом проекте указанный для добавления параметр уже присутствует, но в нем отличается список категорий параметра, то нужные категории будут добавлены (сниматься галочки категорий не будут);
2. Далее если параметр не был найден в целевом проекте, то производится копирование нужного параметра.

3 - Начало работы

3.1 - Установка

Для успешного начала разработки на нашей платформе необходимо выполнить ряд шагов по установке и настройке необходимых инструментов. Следуйте данной инструкции, чтобы правильно настроить среду для работы с Revit и pyRevit.

Установка pyRevit

1. Перейдите на официальный сайт pyRevit и скачайте последнюю версию установщика для пользователя pyRevit_<version>_signed.exe.

pyRevit assets

2. Запустите установщик и следуйте инструкциям на экране для установки pyRevit.

Выбираем путь до места установки, в нашем случае должна быть папка %appdata%\pyRevit-Master как на скриншоте

Выбираем Full instalation

3. После установки откройте Revit и убедитесь, что вкладка pyRevit появилась в интерфейсе.

pyRevit

Установка платформы

1. Запустите PowerShell
2. Запустите следующие команды в PowerShell

Установка вкладки Admin

pyrevit extend ui 00.Admin "https://www.github.com/Bim4Everyone/AdminExtensions"

Установка вкладки 2D

pyrevit extend ui 01.2D "https://www.github.com/Bim4Everyone/2DExtensions"

Установка вкладки BIM

pyrevit extend ui 01.BIM "https://www.github.com/Bim4Everyone/BIMExtensions"

Установка вкладки АР

pyrevit extend ui 02.AR "https://www.github.com/Bim4Everyone/ARExtensions"

Установка вкладки КР

pyrevit extend ui 03.KR "https://www.github.com/Bim4Everyone/KRExtensions"

Установка вкладки ОВиВК

pyrevit extend ui 04.OV-VK "https://www.github.com/Bim4Everyone/HVACExtension"

Установка библиотеки Bim4Everyone

pyrevit extend lib Bim4Everyone "https://www.github.com/Bim4Everyone/Bim4Everyone"

1. После установки откройте Revit и убедитесь, что все установленные вкладки платформы появились в интерфейсе.

Bim4Everyone

Настройка окружения

Доступно в следующей статье: Настройка окружения

3.2 - Настройка окружения

В данном разделе описаны необходимые и рекомендуемые инструменты для разработки платформы. Убедитесь, что перед началом работы на вашем ПК установлен Autodesk Revit, а также установлена сама платформа Bim4Everyone.

3.2.1 - Необходимое ПО

Git

Git - это распределенная система контроля версий файлов.

Установка Git

Перейдите по ссылке и скачайте установочный файл Git for Windows. Запустите его и следуйте инструкциям по установке. Если вы незнакомы с Git, выбирайте значения по умолчанию. Если вы продвинутый пользователь, то вы уже сами знаете, что вам нужно.

Перезапустите ПК.

Настройка Git

Если у вас еще нет аккаунта на GitHub, то необходимо его создать.

В user.name напишите свой логин GitHub:

git config --global user.name "johndoe"

В user.email напишите свой публичный email, который привязан к GitHub:

git config --global user.email johndoe@example.com

Python

Python - это язык программирования, на котором можно легко и быстро писать простые плагины.

Установка Python

Для разработки плагинов на python необходимо установить последнюю версию Python2.7 (не путать с IronPython2.7). Для этого перейдите по ссылке и скачайте установочный файл:

Запустите его и следуйте инструкциям по установке. Выбирайте значения по умолчанию.

После установки перезапустите ПК

Notepad++

Notepad++ - это удобный бесплатный текстовый редактор для любого формата файлов.

Установка notepad++

Перейдите на сайт и скачайте установочный файл. Запустите его и следуйте инструкциям.

3.2.2 - Visual Studio

Visual Studio - это IDE для разработки на C# с поддерживаемой бесплатной версией (Community Edition).

Установка

Перейдите по ссылке на официальный сайт и скачайте загрузочный файл программы установки. Запустите его и следуйте инструкциям по установке Visual Studio Installer. Когда появится окно для установки Visual Studio Community 2022, выберите следующие опции:

В Workloads выберите .NET desktop development:

В Language packs выберите English:

После завершения установки рекомендуется перезапустить ПК.

Настройка аккаунтов в Visual Studio

При первом запуске справа снизу выберите Continue without code:

В правом верхнем углу нажмите Sign in:

В появившемся окне выберите свой аккаунт Microsoft и введите пароль. Создайте аккаунт, если у вас еще нет аккаунта Microsoft. Далее добавьте аккаунт GitHub. Если вы еще не зарегистрировались на GitHub, сделайте это:

Настройка текстового редактора

Перейдите в Tools -> Options и задайте настройки, которые будут вам удобны.

Пример настроек текстового редактора (Text Editor):

Настройка автоформатирования при сохранении

Чтобы код автоматически форматировался в соответствии с .editorconfig, необходимо включить флаг в настройках:

Нажав на Configure Code Cleanup можно задать дополнительные действия:

Установка плагинов для Visual Studio

Перед установкой плагинов необходимо закрыть Visual Studio.

Установка Visual Studio Spell Checker

Данный плагин делает проверку орфографии.

Перейдите на страницу плагина, в Marketplace и скачайте установочный файл. Запустите его и следуйте инструкциям по установке.

Чтобы открыть настройки плагина, прейдите в Tools -> Spell Checker -> Edit Global Configuration:

Добавьте словари английского и русского языка:

Настройте опции проверки орфографии:

Сохраните настройки.

Добавление слов в словарь исключений

Чтобы добавить слово в словарь исключений, необходимо нажать Alt+Enter:

На момент написания этой инструкции в плагине есть особенность: нельзя сразу добавить слово в словарь, если это слово - название класса/пространства имен и прочее:

Обойти это можно, написав комментарий с этим словом, и добавив слово из комментария:

Установка Editor Guidelines

Данный плагин отображает максимальную длину строки в виде вертикальной линии.

Перейдите на страницу плагина, в Marketplace и скачайте установочный файл. Запустите его и следуйте инструкциям по установке.

Чтобы настроить цвет линии, перейдите в Tools -> Options -> Environment -> Fonts and Colors -> Guideline:

Установка VSColorOutput64

Данный плагин раскрашивает консольный вывод в цвета по типу сообщения вывода.

Перейдите на страницу плагина, в Marketplace и скачайте установочный файл. Запустите его и следуйте инструкциям по установке.

Чтобы настроить плагин, перейдите в Tools -> Options -> VSColorOutput64:

Установка dotnet tools

Чтобы установить dotnet tools, откройте powershell. Это можно сделать сразу в Visual Studio. Для этого перейдите в View -> Terminal:

Установка powershell tool

dotnet tool install --global PowerShell

Установка nuke tool

Nuke - это утилита для автоматизации сборки и публикации проектов.

dotnet tool install --global Nuke.GlobalTool

3.2.3 - PyCharm

PyCharm - это IDE для разработки на Python с поддерживаемой бесплатной версией (Community Edition).

Установка

Перейдите по ссылке на официальный сайт и скачайте установочный файл PyCharm Community Edition.

Запустите его и следуйте инструкциям по установке. Выберите следующие опции:

После установки перезапустите ПК

Настройка

Добавление RevitAPIStubs

Скачайте архив с RevitAPIStubs по ссылке. В этом архиве находится python код, который помогает PyCharm делать подсказки по API Revit.

Распакуйте содержимое архива. Папки common и revit:

Добавление интерпретаторов

Перед тем, как добавлять интерпретаторы, убедитесь, что на вашем ПК установлена сама платформа Bim4Everyone.

В главном окне при запуске PyCharm перейдите в раздел Customize -> All settings:

Затем перейдите в раздел Python Interpreter -> Show All

Нажмите + чтобы добавить интерпретатор:

В открывшемся окне выберите раздел Virtual Environment. В качестве Base interpreter укажите путь к python.exe (python2.7 который вы устанавливали выше). Т.к. stub файлы отличаются для каждой версии Revit, то нужно создать интерпретаторы под все версии Revit, которые у вас установлены, и разместить их в отдельных директориях. Директории укажите в Location.

Затем необходимо настроить пути для каждого интерпретатора. Чтобы открыть окно настроек, нажмите ПКМ на интерпретатор и выберите Show Interpreter Paths:

Для каждого добавленного интерпретатора необходимо добавить 4 пути:

• путь к соответствующим stubs файлам из архива, находящимся в revit/20xx (будет разный для каждого интерпретатора).
• путь к common файлам также из архива (будет одинаковый для всех интерпретаторов).
• путь к папке %AppData%\pyRevit-Master\pyrevitlib (будет одинаковый для всех интерпретаторов), которая создается при установке pyRevit.
• путь к папке %AppData%\pyRevit\Extensions\BIM4Everyone.lib (будет одинаковый для всех интерпретаторов), которая создается при установке платформы Bim4Everyone.

PyCharm custom properties

Перейдите в раздел Edit Custom Properties:

И замените весь существующий текст на следующий:

#---------------------------------------------------------------------
# Maximum file size (kilobytes) IDE should provide code assistance for.
# The larger file is the slower its editor works and higher overall system memory requirements are
# if code assistance is enabled. Remove this property or set to very large number if you need
# code assistance for any files available regardless their size.
#---------------------------------------------------------------------
idea.max.intellisense.filesize=40000

#---------------------------------------------------------------------
# Maximum file size (kilobytes) IDE is able to open.
#---------------------------------------------------------------------
idea.max.content.load.filesize=40000

3.2.4 - Плагины для Autodesk Revit

В разработке плагинов для платформы очень помогают существующие плагины от других разработчиков. На данной странице приведены самые полезные из них.

RevitLookup

RevitLookup предоставляет широкие возможности для просмотра и навигации по API объектам в Revit.

Установка

Перейдите на страницу релизов и скачайте установочные файлы для каждой версии Revit, которая у вас установлена. Запустите установочные файлы и следуйте инструкциям по установке.

RevitAddInManager

RevitAddInManager позволяет запускать собранные dll плагинов для их дальнейшей отладки в IDE.

Установка

Перейдите на страницу релизов и скачайте последнюю версию установочного файла. Запустите его и следуйте инструкциям по установке.

4 - Уроки

Здесь будет круто…

4.1 - Создание плагинов

Здесь будет круто…

4.1.1 - Что такое pyRevit?

Здесь будет круто…

4.1.2 - Что такое Bim4Everyone?

Здесь будет круто…

4.1.3 - Разработка на C#

Здесь будет круто…

4.1.4 - Разработка на python

Здесь будет круто…

4.1.5 - OpenSource

Здесь будет круто…

5 - Примеры

Здесь будет круто…

6 - FAQ

Что такое пайревит?

pyRevit - это среда для быстрой разработки под Autodesk Revit. Благодаря pyRevit, можно создавать плагины на python и C#, не отвлекаясь на инфраструктуру. Также имеются широкие возможности для логирования и телеметрии.

Как установить пайревит?

Здесь вы найдете инструкцию по установке pyRevit.

Где скачать платформу?

Скачать последнюю версию установщика платформы можно с github.

Как установить платформу?

Здесь вы найдете инструкцию по установке платформы Bim4Everyone.

Как посмотреть изменения платформы?

Обновления в платформе пишутся в CHANGELOG в репозиторий Bim4EveryoneSetup.

Как настроить логи платформы?

Здесь вы найдете инструкцию по настройке логирования pyRevit. Логи платформы по умолчанию пишутся в журнал Revit. Если у вас запущен сервис телеметрии, то можно также настроить запись логов в него.

Пример настройки трассировки логов в сервер телеметрии через pyRevit CLI:

pyrevit configs log_trace:active enable
pyrevit configs log_trace:level information
pyrevit configs log_trace:server_name your_telemetry_server_url

Как добавить телеметрию в платформу?

Здесь вы найдёте подробную инструкцию по настройке телеметрии в pyRevit. Вы можете развернуть свой сервис телеметрии, используя репозиторий Bim4EveryoneTelemetry. Настройки телеметрии можно задать прямо в установщике платформы при его сборке, или указать через pyRevit CLI.

Пример настройки телеметрии через pyRevit CLI:

pyrevit configs telemetry enable
pyrevit configs telemetry utc yes
pyrevit configs telemetry server your_telemetry_server_url
pyrevit configs apptelemetry enable
pyrevit configs apptelemetry flags 0x4000400004003
pyrevit configs apptelemetry server your_telemetry_server_url
pyrevit configs log_trace:active enable
pyrevit configs log_trace:level information
pyrevit configs log_trace:server_name your_telemetry_server_url

По умолчанию заданные настройки сохраняются в %ProgramData%\pyRevit\pyRevit_config.ini

Как зарепортить баг в платформе?

Если у вас возникла ошибка в pyRevit, то создайте issue в репозитории pyRevit. Если у вас возникла ошибка при установке платформы, то вы также можете создать issue в репозитории Bim4EveryoneSetup, или можете написать в нашу группу в telegram. Если у вас возникла ошибка при использовании какого-то определенного плагина, то аналогично вы можете написать в ту же группу в telegram или создать issue в репозитории соответствующей вкладки:

• 2D
• BIM
• АР
• КР
• ОВиВК

Можно ли запустить платформу на старых версиях Revit?

На данный момент платформа поддерживается для 2022, 2023, 2024 версий Revit. Поддержка более старых версий не осуществляется. Если необходимо, можно при помощи pyRevit CLI включить pyRevit на других версиях Revit, но стабильная работа платформы на них не гарантируется.

Пример команды для включения 2021 версии:

pyrevit attach master default 2021

7 - Внеси свой вклад

Здесь будет круто…