О доступе через COM API

В Navisworks COM существует для 4 различных сценариев:

• Navisworks ActiveX controls;
• Navisworks Automation;
• COM Plug-ins for Navisworks;
• COM 'State' API for Navisworks and ActiveX controls;

Navisworks ActiveX Controls

Данный вид COM-API предназначен для вызова функциональности Navisworks извне (со стороны пользовательских приложений, веб-страниц, иные контейнеры). Можно получать доступ к содержимому моделей, управлять им, открывать в Navisworks файлы. Загрузка файлов осуществляется в отдельном потоке, чтобы предотвратить «зависание» программы, в которой эти файлы были созданы (прим. автора, тут непонятно, или программы, откуда этот скрипт вызывается) File download is done in a separate thread to prevent 'hanging' the containing program..

Используются 2 динамические библиотеки, содержащие COM API, где XX - номер версии Navisworks, для которого библиотеки есть (в оригинальном COM Interface.pdf из SDK они имели номер 14, для Navisworks 2021 номер = 18). Navisworks Redistributable API Library XX (lcodieDX.dll)

# В csproj строка подключения COM-reference будет примерно такой с поправкой на версию XX
<COMReference Include="NavisworksRedistributableAPI18">
  <WrapperTool>tlbimp</WrapperTool>
  <VersionMinor>0</VersionMinor>
  <VersionMajor>1</VersionMajor>
  <Guid>1ae0ca20-712a-5761-b4a6-a891c594f278</Guid>
  <Lcid>0</Lcid>
  <Isolated>false</Isolated>
  <EmbedInteropTypes>true</EmbedInteropTypes>
</COMReference>

• Этот компонент может быть доступен без установленного Navisworks (достаточно только иметь установленный модуль с этим API, возможно имеется в виду NW Freedom) This control is supplied in a Windows Installer merge module and also a self-installing executable.;
• Доступ к управлению моделью и внутренним данным модели (прим. автора For control and internal state access) ;
• Могут быть открыты только файлы проекта Navisworks (*.nwd);
• Поддержка без ограничений 32bit и 64bit версий ОС (прим. автора на 2026й год уже неактуально);
• Доступны только методы API, способные работать в "безлицензионном режиме", либо все, если лицензия как-то загружена в данное контейнерное приложение `Only certain methods in the API will works as the control runs in ‘unlicensed’ mode unless a special runtime license is embedded in the container application.;

Navisworks Integrated API Library XX (lcodieD.dll)

# В csproj строка подключения COM-reference будет примерно такой с поправкой на версию XX
<COMReference Include="NavisworksIntegratedAPI18">
  <WrapperTool>tlbimp</WrapperTool>
  <VersionMinor>0</VersionMinor>
  <VersionMajor>1</VersionMajor>
  <Guid>b55d0ec6-97ab-5ff0-b6e3-a62e2a2e2bf9</Guid>
  <Lcid>0</Lcid>
  <Isolated>false</Isolated>
  <EmbedInteropTypes>true</EmbedInteropTypes>
</COMReference>

• Этот компонент поставляется вместе с устанавливаемым Navisworks;
• Доступ к управлению моделью и внутренним данным модели (прим. автора For control and internal state access) ;
• 32-битная библиотека будет работать только на 32-битной ОС, соответственно, 64-битная только на 64-битной ОС (прим. автора на 2026й год уже неактуально, всё ушло на 64-битные системы);
• Могут быть открыты различные файлы, не только файлы проекта Navisworks (*.nwd);
• Всё API доступно к вызову, если основной продукт (Navisworks) лицензирован; Примечание: в оригинальном COM Interface.pdf из SDK имеется заметка, что при разработке на 32-битной Visual Studio под 64-битные библиотеки могут быть сложности, и надо вручную регистрировать 32-битные библиотеки через regsvr32.exe lcodied.dll;

Таким образом, Navisworks Integrated API - это способ взаимодействия с Navisworks из другого процесса с полным доступом к имеющемуся API.

MDI / SDI Режимы

Для каждой из упомянутых выше библиотек управления (Redistributable и Integrated) имеются 2 режима работы с ограничениями:

MDI: Multiple Document Support

• В одном процессе может использоваться несколько элементов управления;
• Поддержка плагинов отсутствует. Поэтому плагины, расширяющие экспорт и работу с рецензированием недоступны;

SDI: Single Document Support

• В одном процессе может использоваться только один элемент управления;
• Поддержка плагинов имеется;

Встраивание в HTML

Возможно встроить в HTML-код страницы сценарий, обращающийся к COM API Navisworks. Для внедрения в страницу функциональности просмотра некоторой модели. В современной практике это не используется, в угоду WEB API различных систем (в отношении Autodesk -- Forge, Autodesk Docs и т.д.).

<object
    id="NavisworksControl"
    classid="CLSID:XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"  <!-- Тот самый CLSID -->
    codebase="http://ваш_сайт/Installers/NavisworksActiveX.exe" <!-- Откуда качать, если нет -->
    width="800"
    height="600">
    <param name="FileName" value="model.nwc"> <!-- Какой файл открыть -->
</object>

• CLSID (classid) - это Guid, характеризующий целевую библиотеку (см. примеры выше для cspoj)
• codebase - это путь для загрузки элемента управления, если в данной системе отсутствует компонент для указанного classid;
• данный подход работает только в Windows (т.к. вызывается внешний COM);

COM 'State' API for Navisworks and ActiveX controls

Элементы управления Navisworks и его ActiveX используют общий API для доступа к внутренним функциям Несмотря на сходство, некоторые интерфейсы и классы могут присутствовать только в одной DLL-библиотеке. Ниже основные особенности COM API и рекомендации по работе с ним.

Имена COM-интерфейсов

Каждый объект имеет только один соответствующий ему интерфейс, содержащий все методы. Имя интерфейса для конкретного объекта аналогично имени самого объекта. Например, объект "nwOpState" имеет интерфейс InwOpState.

Объект верхнего уровня

Объект "nwOpState" — это объект верхнего уровня, отвечающий за состояние модели Navisworks. Ниже него находится иерархия других объектов, доступных через свойства, методы и коллекции. Состояние ("nwOpState") также позволяет обрабатывать COM-события, когда происходят различные действия в пользовательском интерфейсе Navisworks.

Наследование методов интерфейсов

Интерфейс каждого объекта напрямую или косвенно наследуется от InwBase. Он содержит стандартные методы. Например, InwOpState наследуется от InwBase. Таким образом, он содержит все методы и свойства InwBase.

Коллекции

В практике COM все индексы начинаются с 1. Все коллекции имеют стандартный набор методов, но некоторые из них могут быть не реализованы для некоторых коллекций. Одна коллекция может содержать различные типы объектов. Обычно все они наследуются от одного общего типа объекта.

Идентификация объектов

Интерфейс InwBase содержит readonly-свойство ObjectName. Его можно использовать для идентификации неизвестных объектов вместо выполнения операций "QueryInterface" или "Set" в Visual Basic или as в .NET. Это единственный способ идентификации объектов в языках с динамической типизацией.

Создание новых объектов

Объекты Navisworks нельзя создать м помощью директивы new. Вместо этого используйте метод ObjectFactory у COM-оболочки состояния документа InwOpState.

Перечисления

В языках с динамической типизацией нельзя использовать встроенные перечисления (enum) из COM API. Для перехода к ним из строкового представления используйте метод GetEnum у у COM-оболочки состояния документа InwOpState, это позволит сделать код более читаемым.

При разработке на .NET такой проблемы нет, enum можно использовать без ограничений.

Сравнение объектов

Если вы хотите установить, ссылаются ли 2 ссылки на один и тот же объект, не сравнивайте их COM-оболочки, вместо этого вызывайте метод PtrEquals у COM-оболочки состояния документа InwOpState.

Navisworks Automation

В Navisworks реализована ​​базовая поддержка автоматизации. Цель состоит в том, чтобы позволить пользователям программно запускать и управлять продуктом с помощью скриптовых языков (Visual Basic, VBA или VBScript прим. автора - из оригинальной справки). Пользователь также может получать доступ к внутреннему состоянию приложения и управлять им (т.е. работать с COM-оболочкой модели InwOpState).

Об установке нескольких версий Navisworks

С версий Navisworks 2017 каждый из продуктов (Manage и Simulate) может быть установлен параллельно. Для целей COM-автоматизации они идентичны, и фактически GUID'ы (CLSID) для каждого продукта идентичны. При запуске через COM запускается тот продукт, который был установлен или запущен последним. Например, если вы установили Navisworks Manage 2017, а затем установили Navisworks Simulate 2017, то при запуске продукта через COM запустится Navisworks Simulate. Но если пользователь впоследствии запустит Navisworks Manage, то при выполнении следующего скрипта с COM запустится именно он.

Navisworks Licensing

Какая-либо COM-автоматизация доступна только для лицензионных версий Navisworks.

Подключение к процессу

Осуществляется по идентификатору приложения "Navisworks.Document"

Типы COM-библиотек

• Navisworks Automation Library XX - для взаимодействия с приложением Navisworks;
• Navisworks Integrated API Library XX - для взаимодействия с моделью в Navisworks;

COM-Plugins

Для Navisworks можно создавать COM-плагины. Они расширяют базовую функциональность продукта и доступны на соответствующих вкладках ленты продукта. Прим. автора - имеется подозрение, что плагины ограничены языком Visual Basic (по документации).

Существует 4 типа плагинов, подробнее см. раздел про них. Каждый плагин должен реализовывать базовый COM-интерфейс для плагина InwPlugin. Указывается имя плагина, его настройки в зависимости от типа плагина. Плагины могут быть созданы в виде DLL-файлов или исполняемых файлов. Преимущество исполняемых файлов заключается в возможности отображения немодальных диалогов.

В процессе инициализации плагина в Navisworks вы передаете плагину набор флагов. Это будет влиять на его поведение. Для каждого плагина можно добавить страницу параметров. На ней можно отображать пользовательские свойства типов CLng (int 64), CDbl (double), CBool (bool), CDate (DateTime) и CStr (string).

Export-plugin

Плагины экспорта должны реализовывать интерфейс InwExportPlugin. Плагины экспорта позволяют осуществлять полностью настраиваемый экспорт данных путем добавления их в меню Navisworks. Основной метод, заслуживающий внимания, — это iExport, который будет вызываться при экспорте. Автор плагина может использовать API COM-оболочки приложения InwOpState и всю мощь VB для выполнения любых необходимых действий. Флаги позволяют добавлять пункты меню в меню «Вид», «Вывод» и «Надстройки». Также, в альтернативу добавления кнопок на ленты, вы можете использовать подписки на события InwOpState для отслеживания происходящих событий в модели.

Clash Detective Plug-ins (проверки на коллизии\пересечения)

Плагины, добавляющие исключения при обработке коллизий, должны реализовывать интерфейс InwClashPlugin. Плагины позволяют игнорировать определенные конфликты (для некоторых заданных условий). При обнаружении каждого конфликта в Navisworks у загруженных плагинов с данным типом будет вызываться метод iIgnore с целью оставить или отбросить обнаруженную коллизию.

Property Plug-ins (плагины, работающие со свойствами)

Плагины свойств должны реализовывать интерфейс InwPropertyPlugin. Плагины свойств позволяют переопределять то, что отображается при щелчке правой кнопкой мыши по объекту. Результат может представлять текстовую строку (реализация iContentsText) или список свойств (реализация iContentsProperties).

Presenter Plug-ins

Плагины для "Визуализации" должны реализовывать интерфейс InwPresenterPlugin. Плагины используются для применения текстур к модели. Загруженные плагины отображаются на вкладке «Правила» на вкладке "Визуализация".

Загрузка плагинов

В настоящее время (прим. автора - на 2017 версию как минимум) единственный способ заставить Navisworks загружать COM-плагины — это добавить их строку «ProgId» в реестр. Настроек в UI для этого не предусмотрено. Для загрузки плагинов необходимо перезапустить Navisworks.

Поскольку каждый продукт начиная с Navisworks 2017 может быть установлен параллельно, у каждого из них будет свой набор записей в реестре. Это означает, что вам необходимо зарегистрировать свой плагин в каждой версии продукта, с которой он совместим. Ключи реестра для каждого плагина показаны в таблице ниже.