.. role:: blue
   :class: blue

Архитектура дерева модели
=========================
.. _Model_Tree_Architecture:

Для модели, сформированной с использованием объектов геометрического ядра C3D, приняты следующие соглашения:

- Документ эквивалентен корневому компоненту (компоненту высшего уровня).
- Компоненту всегда соответствует объект типа :blue:`MbAssembly` в случае формата с граничным представлением. В случае формата с полигональным представлением в качестве компонента допустим объект типа :blue:`MbMesh`. Ожидается, что на компонент назначены свойства, и это выражается в том, что компонент обладает атрибутами типа :blue:`MbProductInfo` и :blue:`MbPersonOrganizationInfo`.
- Собственными объектами компонента могут быть объекты типа :blue:`MbSolid`, :blue:`MbWireFrame`, :blue:`MbPointFrame`, :blue:`MbSpaceInstance` (как с объектами геометрии внутри, так и содержащие элементы аннотаций MbPMI) и :blue:`MbPlaneInstance` для форматов с граничным представлением, либо :blue:`MbMesh` для полигональных форматов, которые лежат в :blue:`MbAssembly`.
- Вложенность компонент и их позиционирование осуществляется с помощью объектов типа :blue:`MbInstance`. :blue:`MbInstance` лежит в компоненте верхнего уровня и ссылается на компонент нижнего уровня. Циклические зависимости недопустимы.

Подход, согласно которому модель для обмена данными формируется средствами геометрического ядра C3D, имеет ряд недостатков. Наиболее существенный из них заключается в том, что использование конкретных объектов и конкретной конфигурации затрудняет развитие функционала - внесение любых изменений приведёт к необходимости внесения ответных изменений у всех пользователей. Использование интерфейсов модели, компонента и вставки, реализуемых на стороне пользователя, даёт последним независимость от конкретной реализации.

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

.. figure:: /CONVERTER/pictures/T.1.7.1.png
   :width: 20cm
   :align: center

- Документ :blue:`ItModelDocument`\() содержит в себе компонент высшего уровня.
- Компоненты бывают двух типов: детали :blue:`ItModelPart` и сборки :blue:`ItModelAssembly`. Разница между ними лишь в интерпретации, оба типа могут ссылаться на компоненты более низкого уровня.
- Собственными объектами компонентов могут быть объекты типа :blue:`MbSolid`, :blue:`MbWireFrame`, :blue:`MbPointFrame`, :blue:`MbSpaceInstance` и :blue:`MbPlaneInstance`.
- Вложенность компонент и их позиционирование осуществляется с помощью объектов :blue:`ItModelInstance`. Циклические зависимости недопустимы.

:blue:`ItModelInstanceProperties` --- базовый класс, предок интерфейсов :blue:`ItModelPart`, :blue:`ItModelAssembly`, :blue:`ItModelInstance`. В интерфейсе объявлены методы:

.. code-block:: cpp

   virtual bool SetAttributes( const c3d::AttrSPtrVector & /*attributes*/ );

   virtual c3d::AttrSPtrVector GetAttributes();

   virtual void GetRequirements( AnnotationSptrVector &, eTextForm ); (устаревший)

   virtual void SetRequirements( const AnnotationSptrVector & ); (устаревший)


Интерфейсы :blue:`ItModelPart` и :blue:`ItModelAssembly` имеют одинаковый набор методов, поэтому их можно считать идентичными с точностью до интерпретации.
Назначение свойств компонентов, визуальных свойств и технических требований реализуется посредством методов базового класса :blue:`ItModelInstanceProperties`.

Метод :blue:`PureFileName`\() вызывается при экспорте и возвращает строку, смысл которой -- имя файла компонента.

**Методы для работы с собственными объектами**:

.. code-block:: cpp

   void GetItems( std::vector< SPtr<MbItem> > & items,
                  MbeGettingItemType            itemType,
                  bool                          includeInvisible );

   void AddItems( const std::vector< SPtr<MbItem> > & items );

   GetItems();

   AddItems();

Метод :blue:`GetItems`\() предназначен для выдачи элементов в контейнер с использованием фильтров типа и видимости, которые формируются на основе значений, возвращаемых методом IConvertorProperty3D:: :blue:`GetIoPermission`\().

Метод :blue:`AddItems`\() используется при импорте и предназначен для добавления элементов в компонент.

**Методы для работы со вставками**:

.. code-block:: cpp

   SPtr<ItModelInstance> PrepareInstance();

   SPtr<ItModelInstance> NextInstance( bool includeInvisible );

   PrepareInstance();

   NextInstance();

Метод :blue:`PrepareInstance`\() предназначен для осуществления вставки компонента при импорте.

Метод :blue:`NextInstance`\() представляет собой итератор вставок при экспорте.
Предполагается, что итератор готов к выдаче вставок с начала. Признаком окончания является возврат нулевого указателя.
Значение фильтра видимости в процессе обхода соответствует результату вызова метода IConvertorProperty3D:: :blue:`GetIoPermission`\( iop_wInvisible ).

Метод :blue:`GetAnnotationItems`\( eTextForm **textForm** ) является устаревшим.

**Методы для импорта через плагины**:

- Метод

.. code-block:: cpp

   virtual void ItModelPart::AddMappedItem( MbItem &                    item,
                                            MbPlacement3D const &       placement,
                                            c3d::AttrSPtrVector const & attributes );

позволяет добавить объект с заданной локальной системой координат в корень сборки при импорте.
Метод актуален только для формата IFC (cм. параграф :ref:`Импорт IFC <IFC_Import>`).

Аргументы:

**item** -- объект, добавляемый в модель.

**placement** -- локальная система координат.

- Метод

.. code-block:: cpp

   virtual SPtr<MbInstance> ItModelPart::NextMappedItem() const;

возвращает объект с заданной локальной системой координат или nullptr.
Метод актуален только для формата IFC (cм. параграф :ref:`Импорт IFC <IFC_Import>`).

- Метод

.. code-block:: cpp

   virtual void ItModelPart::AddAxesGrid( c3d::ItemSPtr const & );

позволяет добавить группу конструкционных осей.
Метод актуален только для формата IFC (cм. параграф :ref:`Импорт IFC <IFC_Import>`).

- Метод

.. code-block:: cpp

   virtual c3d::ItemSPtr ItModelPart::NextAxesGrid() const;

возвращает очередную группу конструкционных осей или нуль в случае исчерпания.
Метод актуален только для формата IFC (cм. параграф :ref:`Импорт IFC <IFC_Import>`).

- Метод

.. code-block:: cpp

   virtual c3d::ItemSPtr NextSpatialAxis() const { return c3d::ItemSPtr{}; }

возвращает очередную пространственную ось или нуль в случае исчерпания.

- Метод

.. code-block:: cpp

   virtual void AddSpatialAxis( c3d::ItemSPtr const & );

позволяет добавить очередную пространственную ось.

- Метод

.. code-block:: cpp

   virtual c3d::ItemSPtr ItModelPart::NextBoundaryItem();

возвращает следующий объект, ограничивающий площадь или объем.
Метод актуален только для формата IFC (cм. параграф :ref:`Импорт IFC <IFC_Import>`).

- Метод

.. code-block:: cpp

   virtual SPtr<MbAssistingItem> ItModelPart::NextCoordinateSystem();

возвращает очередную систему координат или нуль в случае исчерпания.
Включение и выключение метода при импорте и экспорте возможно с помощью фильтрации :blue:`SetIoPermission`\( iop_rCS / iop_wCS ).

**Методы для работы с модельным документом и сборками**:

.. code-block:: cpp

   virtual void ItModelPart::AddBoundaryItem( c3d::ItemSPtr const &);

добавляет объект, ограничивающий площадь или объем.

.. code-block:: cpp

   virtual void ItModelPart::AddCoordinateSystem( SPtr<MbAssistingItem> const &);

позволяет добавить систему координат. Включение и выключение метода при импорте и экспорте возможно с помощью фильтрации :blue:`SetIoPermission`\( iop_rCS / iop_wCS ).

Интерфейсы :blue:`ItModelPart` и :blue:`ItModelAssembly` объявлены в файле *conv_model_document.h*.


**Вставки ItModelInstance**

Наследование интерфейса вставки :blue:`ItModelInstance` от :blue:`ItModelInstanceProperties` сложилось исторически и сохранено для совместимости. В рамках сложившегося подхода корректным является только назначение собственных визуальных свойств вставке.

Метод void * :blue:`GetId`\() позволяет различать вставки эквивалентных компонентов. Если различные вставки возвращают одинаковое значение, то эквивалентность определяется по результатам анализа содержания. В процессе экспорта конвертер стремится к оптимизации модели за счёт многократного использования эквивалентных компонент. Пользователь может предоставить информацию о том, какие компоненты точно не являются эквивалентными для сокращения вычислительных затрат при экспорте.

При экспорте для получения такой информации о вставке как локальная система координат вставки, содержимое вставки, отсутствие наполнения вставки используются методы:

.. code-block:: cpp

   bool GetPlacement( MbPlacement3D & place );

   bool IsAssembly();

   bool IsEmpty();

Если вставка не пуста, то в зависимости от результата метода :blue:`IsAssembly`\() вызывается один из методов:

.. code-block:: cpp

   SPtr<ItModelAssembly> GetInstanceAssembly();

   SPtr<ItModelPart> GetInstancePart();

Эти методы возвращают интерфейс компонента, на который ссылается вставка.

Для создания компонентов при импорте предназначены методы:

.. code-block:: cpp

   SPtr<ItModelAssembly> CreateAssembly(const MbPlacement3D &              place,
                                        const std::vector<SPtr<MbItem> > & componentItems,
                                        const c3d::path_string &           fileName );

.. code-block:: cpp

   SPtr<ItModelPart> CreatePart(      MbPlacement3D &              place,
                                const std::vector<SPtr<MbItem> > & componentItems,
                                const c3d::path_string &           fileName );

Результатом работы этих методов является интерфейс компонента, размещение которого в компоненте верхнего уровня описано локальной системой координат **place**, компонент наполняется элементами из контейнера **componentItems**, ему соответствует имя файла **fileName**.

Для размещения во вставке ранее созданных компонентов используются методы:

.. code-block:: cpp

   bool SetAssembly( const MbPlacement3D &   place,
                     const ItModelAssembly * existing );

.. code-block:: cpp

   bool SetPart( const MbPlacement3D & place,
                 const ItModelPart *   existing );

Размещение компонента **existing** определяется локальной системой координат **place**.

Интерфейс :blue:`ItModelInstance` объявлен в файле *conv_model_document.h*.