.. role:: blue
   :class: blue

Model Tree Architecture
=======================
.. _Model_Tree_Architecture_:

For a model created by using C3D geometric kernel objects, the following conventions are adopted:

- A document is equivalent to a root component (a top-level component).
- A component always corresponds to an object of type :blue:`MbAssembly` in the case of a boundary representation format. In the case of a polygonal representation format, an object of type :blue:`MbMesh` is allowed as a component. The component is expected to have assigned properties, which is expressed by the fact that the component has attributes of type :blue:`MbProductInfo` and :blue:`MbPersonOrganizationInfo`.
- Own objects of a component can be objects of type :blue:`MbSolid`, :blue:`MbWireFrame`, :blue:`MbPointFrame`, :blue:`MbSpaceInstance` (both with geometry objects inside and containing MbPMI annotation elements), and :blue:`MbPlaneInstance` for boundary representation formats, or :blue:`MbMesh` for polygonal formats, which reside in :blue:`MbAssembly`.
- Nesting of components and their positioning are performed by using objects of type :blue:`MbInstance`. :blue:`MbInstance` resides in a higher-level component and references a lower-level component. Cyclic dependencies are not allowed.

The approach in which a data exchange model is created by means of the C3D geometric kernel has several drawbacks. The most significant one is that the use of specific objects and a specific configuration makes it difficult to evolve the functionality, because any changes will require corresponding changes on the user side. The use of model, component, and instance interfaces implemented on the user side gives users independence from a specific implementation.

In terms of interfaces, the model tree architecture looks as follows:

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

- A document :blue:`ItModelDocument`\() contains a top-level component.
- Components are of two types: parts :blue:`ItModelPart` and assemblies :blue:`ItModelAssembly`. The difference between them lies only in interpretation, and both types can reference lower-level components.
- Own objects of components can be objects of type :blue:`MbSolid`, :blue:`MbWireFrame`, :blue:`MbPointFrame`, :blue:`MbSpaceInstance`, and :blue:`MbPlaneInstance`.
- Nesting of components and their positioning are performed by using :blue:`ItModelInstance` objects. Cyclic dependencies are not allowed.

.. role:: blue
   :class: blue

:blue:`ItModelInstanceProperties` is a base class, the ancestor of the :blue:`ItModelPart`, :blue:`ItModelAssembly`, :blue:`ItModelInstance` interfaces. The following methods are declared in the interface:

.. code-block:: cpp

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

   virtual c3d::AttrSPtrVector GetAttributes();

   virtual void GetRequirements( AnnotationSptrVector &, eTextForm ); (deprecated)

   virtual void SetRequirements( const AnnotationSptrVector & ); (deprecated)


The :blue:`ItModelPart` and :blue:`ItModelAssembly` interfaces have the same set of methods, so they can be considered identical up to interpretation.
The assignment of component properties, visual properties, and technical requirements is implemented through the methods of the :blue:`ItModelInstanceProperties` base class.

The :blue:`PureFileName`\() method is called during export and returns a string whose meaning is the component file name.

**Methods for working with own items**:

.. code-block:: cpp

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

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

   GetItems();

   AddItems();

The :blue:`GetItems`\() method is intended to output items into a container using type and visibility filters, which are formed based on the values returned by the IConvertorProperty3D:: :blue:`GetIoPermission`\() method.

The :blue:`AddItems`\() method is used during import and is intended for adding items to a component.

**Methods for working with instances**:

.. code-block:: cpp

   SPtr<ItModelInstance> PrepareInstance();

   SPtr<ItModelInstance> NextInstance( bool includeInvisible );

   PrepareInstance();

   NextInstance();

The :blue:`PrepareInstance`\() method is intended for inserting a component during import.

The :blue:`NextInstance`\() method is an iterator of instances during export.
It is assumed that the iterator is ready to output instances from the beginning. The sign of completion is returning a null pointer.
The visibility filter value during traversal corresponds to the result of calling IConvertorProperty3D:: :blue:`GetIoPermission`\( iop_wInvisible ).

The :blue:`GetAnnotationItems`\( eTextForm **textForm** ) method is deprecated.

**Methods for import via plugins**:

- The method

.. code-block:: cpp

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

allows you to add an item with a given local coordinate system to the root of an assembly during import.
The method is relevant only for the IFC format (see :ref:`IFC Import <IFC_Import_>`).

Arguments:

**item** -- an item added to the model.

**placement** -- a local coordinate system.

- The method

.. code-block:: cpp

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

returns an item with a given local coordinate system or nullptr.
The method is relevant only for the IFC format (see :ref:`IFC Import <IFC_Import_>`).

- The method

.. code-block:: cpp

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

allows you to add a grid of construction axes.
The method is relevant only for the IFC format (see :ref:`IFC Import <IFC_Import_>`).

- The method

.. code-block:: cpp

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

returns the next grid of construction axes or null in case of depletion.
The method is relevant only for the IFC format (see :ref:`IFC Import <IFC_Import_>`).

- The method

.. code-block:: cpp

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

returns the next spatial axis or null in case of depletion.

- The method

.. code-block:: cpp

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

allows you to add the next spatial axis.

- The method

.. code-block:: cpp

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

returns the next item that bounds an area or a volume.
The method is relevant only for the IFC format (see :ref:`IFC Import <IFC_Import_>`).

- The method

.. code-block:: cpp

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

returns the next coordinate system or null in case of depletion.
Enabling and disabling this method during import and export is possible by using the :blue:`SetIoPermission`\( iop_rCS / iop_wCS ) filtering.

**Methods for working with a model document and assemblies**:

.. code-block:: cpp

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

adds an item that bounds an area or a volume.

.. code-block:: cpp

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

allows you to add a coordinate system. Enabling and disabling this method during import and export is possible by using the :blue:`SetIoPermission`\( iop_rCS / iop_wCS ) filtering.

The :blue:`ItModelPart` and :blue:`ItModelAssembly` interfaces are declared in the *conv_model_document.h* file.

**ItModelInstance Instances**

The inheritance of the :blue:`ItModelInstance` instance interface from :blue:`ItModelInstanceProperties` has been established historically and is preserved for compatibility. Within the framework of the established approach, only the assignment of custom visual properties to an instance is correct.

The void * :blue:`GetId`\() method allows distinguishing instances of equivalent components. If different instances return the same value, the equivalence is determined by the results of the content analysis. During the export process, the converter seeks to optimize the model by reusing equivalent components. A user can provide information about which components are definitely not equivalent to reduce computational costs during export.

During export, the following methods are used to obtain such information about an instance as the local coordinate system of the instance, the content of the instance, and the absence of instance content:

.. code-block:: cpp

   bool GetPlacement( MbPlacement3D & place );

   bool IsAssembly();

   bool IsEmpty();

If an instance is not empty, then depending on the result of the :blue:`IsAssembly`\() method, one of the following methods is called:

.. code-block:: cpp

   SPtr<ItModelAssembly> GetInstanceAssembly();

   SPtr<ItModelPart> GetInstancePart();

These methods return the interface of the component referenced by the instance.

The following methods are intended for creating components during import:

.. 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 );


The result of these methods is a component interface whose placement in the top-level component is described by the local coordinate system **place**, the component is filled with elements from the **componentItems** container, and it corresponds to the file name **fileName**.

The following methods are used to place previously created components in an instance:

.. code-block:: cpp

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

.. code-block:: cpp

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

The placement of the **existing** component is defined by the local coordinate system **place**.

The :blue:`ItModelInstance` interface is declared in the *conv_model_document.h* file.