.. role:: blue
   :class: blue


ItModelDocument Model Document
====================================
.. _ItModelDocument_Model_Document:


The :blue:`ItModelDocument` interface is one of the interfaces that allow passing data with a complex tree-like multicomponent structure, in which multiple reuse of components is allowed. The document provides two ways to work with a model: 

- Direct use of the model constructed with C3D geometric kernel objects.
- A user implements the :blue:`ItModelPart`, :blue:`ItModelAssembly`, :blue:`ItModelInstance` interfaces and the methods that work with their implementations. The converter, in turn, calls interface methods of the returned objects.

The interface methods are grouped as follows:

**a) Group of methods intended for working with the model directly:**

1. Method for setting the root element of a model:

.. code-block:: cpp

   virtual void C3dModelDocument::SetContent( MbItem* content );

2. Method for obtaining the model content:

.. code-block:: cpp

   virtual MbItem* GetContent();

3. Method (deprecated)

.. code-block:: cpp

   virtual map_of_visual_items C3dModelDocument::GetAnnotationItems( eTextForm form );

returns annotation items corresponding to the geometric model elements.

Arguments:

**eTextForm** -- text representation form.

4. Method (deprecated)

.. code-block:: cpp

   virtual void SetAnnotationItems( const map_of_visual_items& visItems );

allows setting dimensions.

**b) Group of methods intended for constructing a model during import:**

1. Method

.. code-block:: cpp

   virtual ModelAssemblyPtr C3dModelDocument::CreateAssembly( 
       const std::ItemsSPtrVector& componentItems, 
       const c3d::string_t&        fileName 
   );

allows creating a document with a new assembly during import.

Arguments:

**fileName** -- assembly name;

**componentItems** -- bodies added to the assembly.

2. Method

.. code-block:: cpp

   virtual ModelPartPtr C3dModelDocument::CreatePart( 
       const c3d::ItemsSPtrVector& componentItems, 
       const c3d::string_t&        fileName 
   );

allows creating a document with a new part on import and increases the reference counter of the resulting document by 1.

Arguments:

**componentItems** -- bodies added to the part.

**fileName** -- part name.

3. Method

.. code-block:: cpp

   virtual bool C3dModelDocument::FinishImport( IProgressIndicator * indicator );

allows completing import and saving the document. Returns *true* if the operation is successful, *false* otherwise.

Arguments:

**indicator** -- an object for displaying the process progress.

**c) A group of methods intended for obtaining related model components during export**:

1. bool :blue:`IsAssembly`\(); // whether the model is an assembly  

2. bool :blue:`IsEmpty`\(); // whether the model is empty (contains neither a part nor an assembly)


3. The method

.. code-block:: cpp

   virtual ModelAssemblyPtr C3dModelDocument::GetInstanceAssembly();

allows you to get the assembly associated with the model document.


4. The method

.. code-block:: cpp

   virtual ModelPartPtr C3dModelDocument::GetInstancePart();

allows you to get the part associated with the model document.


5. The method

.. code-block:: cpp

   bool C3dModelDocument::MakeAssembliesUnique();

converts all assemblies and instances into unique components.

Since it is not known in advance which implementation will be used for data transfer, on import both the :blue:`SetContent`\() method and one of the :blue:`CreateAssembly`\() or :blue:`CreatePart`\() methods are called, depending on the import result. Accordingly, on export the :blue:`GetInstanceAssembly`\() or :blue:`GetInstancePart`\() methods are called first depending on the :blue:`IsAssembly`\() result, and only if the converter fails to construct the model, the :blue:`GetContent`\() method is called.

The C3D geometric kernel provides a standard implementation of the :blue:`ItModelDocument` interface: :blue:`C3DModelDocument`. During import, the model is constructed using standard implementations of the :blue:`ItModelPart`, :blue:`ItModelAssembly`, :blue:`ItModelInstance` interfaces. On export, you can either define a model using the :blue:`SetContent` method or using implementations of the :blue:`ItModelPart`, :blue:`ItModelAssembly`, :blue:`ItModelInstance` interfaces.

The :blue:`ItModelDocument` interface and the :blue:`C3DModelDocument` class are declared in the *conv_model_document.h* file.