.. role:: blue
   :class: blue


How to Work with the Converter
===============================
.. _How_to_Work_with_the_Converter_:

Converters provide tools for exporting and importing :blue:`MbModel`, :blue:`MbItem` models and custom implementations of :blue:`ItModelDocument` documents.

A group of functions designed for data exchange through files is located in the *conv_model_exchange.h* file and declared in the c3d namespace:

The function

.. code-block:: cpp

   MbeConvResType c3d::ImportFromFile(       MbModel &              model,
                                       const path_string &          fileName,
                                             IConvertorProperty3D * prop = nullptr,
                                             IProgressIndicator *   indicator = nullptr );

allows reading an exchange format file into a model.


The function

.. code-block:: cpp

   MbeConvResType c3d::ImportFromFile(       c3d::ItemSPtr &        item,
                                       const path_string &          filePath,
                                             IConvertorProperty3D * prop = nullptr,
                                             IProgressIndicator *   indicator = nullptr );

allows reading an exchange format file into an item.


The function

.. code-block:: cpp

   MbeConvResType c3d::ImportFromFile(       ItModelDocument &      mDoc,
                                       const path_string &          filePath,
                                             IConvertorProperty3D * prop = nullptr,
                                             IProgressIndicator *   indicator = nullptr );


allows reading an exchange format file into a model.


The function

.. code-block:: cpp

   MbeConvResType c3d::ExportIntoFile(       MbModel &              model,
                                       const path_string &          filePath,
                                             IConvertorProperty3D * prop = nullptr,
                                             IProgressIndicator *   indicator = nullptr );


allows writing a model to an exchange format file.


The function

.. code-block:: cpp

   MbeConvResType c3d::ExportIntoFile(       MbItem &               item,
                                       const path_string &          filePath,
                                             IConvertorProperty3D * prop = nullptr,
                                             IProgressIndicator *   indicator = nullptr );


allows writing an item to an exchange format file.


The function

.. code-block:: cpp

   MbeConvResType c3d::ExportIntoFile(       ItModelDocument &      mDoc,
                                       const path_string &          filePath,
                                             IConvertorProperty3D * prop = nullptr,
                                             IProgressIndicator *   indicator = nullptr );


allows writing a model document to an exchange format file.

The function arguments are:

- **model** -- the exported or imported geometric model;
- **item** -- the model item;
- **mDoc** -- the model document;
- **fileName (filePath)** -- the full path to the file;
- *prop* -- the implementation of the converter properties interface;
- *indicator* -- the progress indicator.


During import, the exchange format is determined based on the file extension.

A group of functions implementing the transfer of models to exchange formats through memory:

.. code-block:: cpp

   MbeConvResType c3d::ImportFromBuffer(       MbModel &              model,
                                         const C3DExchangeBuffer &    buffer,
                                               MbeModelExchangeFormat modelFormat,
                                               IConvertorProperty3D * prop = nullptr,
                                               IProgressIndicator *   indicator = nullptr );

.. code-block:: cpp

   MbeConvResType c3d::ImportFromBuffer(       c3d::ItemSPtr &        item,
                                         const C3DExchangeBuffer &    buffer,
                                               MbeModelExchangeFormat modelFormat,
                                               IConvertorProperty3D * prop = nullptr,
                                               IProgressIndicator *   indicator = nullptr );

.. code-block:: cpp

   MbeConvResType c3d::ImportFromBuffer(       ItModelDocument &      mDoc,
                                         const C3DExchangeBuffer &    buffer,
                                               MbeModelExchangeFormat modelFormat,
                                               IConvertorProperty3D * prop = nullptr,
                                               IProgressIndicator *   indicator = nullptr );

.. code-block:: cpp

   MbeConvResType c3d::ExportIntoBuffer( MbModel &              model,
                                         MbeModelExchangeFormat modelFormat,
                                         C3DExchangeBuffer &    buffer,
                                         IConvertorProperty3D * prop = nullptr,
                                         IProgressIndicator *   indicator = nullptr );


.. code-block:: cpp

   MbeConvResType c3d::ExportIntoBuffer( MbItem &               item,
                                         MbeModelExchangeFormat modelFormat,
                                         C3DExchangeBuffer &    buffer,
                                         IConvertorProperty3D * prop = nullptr,
                                         IProgressIndicator *   indicator = nullptr );


.. code-block:: cpp

   MbeConvResType c3d::ExportIntoBuffer( ItModelDocument &      item,
                                         MbeModelExchangeFormat modelFormat,
                                         C3DExchangeBuffer &    buffer,
                                         IConvertorProperty3D * prop = nullptr,
                                         IProgressIndicator *   indicator = nullptr );


The function arguments are:

- **model** -- the exported or imported geometric model;
- **item** -- the model item;
- **mDoc** -- the model document;
- **modelFormat** -- the exchange file format;
- **buffer** -- the buffer;
- **data** -- the buffer address in memory;
- *prop* -- the converter settings;
- *indicator* -- the progress indicator.

The :blue:`ImportFromFile`\(), :blue:`ImportFromBuffer`\() functions perform import of geometric models:

-- STL, OBJ formats;

-- SAT/SAB format up to version 22.0 inclusive;

-- IGES format version 5.3;

-- JT format versions 8.0 — 11.x;

-- Parasolid format up to version 25.0 inclusive;

-- STEP format with supported application protocols 203, 214;

-- VRML format version 2.0.

The :blue:`ExportIntoFile`\(), :blue:`ExportInfoBuffer`\() functions perform export of geometric models:

-- STL, OBJ formats;

-- SAT/SAB format up to version 22.0 inclusive;

-- IGES format version 5.3;

-- JT format version 9.5;

-- Parasolid format up to version 10.0 inclusive;

-- STEP format with supported application protocols 203, 214;

-- VRML format version 2.0.

The result of :blue:`FullFilePath`\() of the *prop* argument is used to determine the exchange file format only if the value of **modelFormat** is equal to *mxf_autodetect*.

The responsibility for deleting the buffer that is created and filled by the :blue:`ExportIntoBuffer`\() function rests with the user. To free memory, it is recommended to use the *delete*\[] operator.

Another method of importing and exporting a model is to call the methods of the :blue:`IConverter3D` converter.

To start working with the converter, it is necessary to obtain its instance. The function IConverter3D * :blue:`GetConvertor3D`\() defined in the global scope creates a converter that can perform import and export of models in any of the supported formats. The function has no parameters. If successful, the function returns a converter, otherwise it returns a null pointer.

The function is declared in the *conv_model_exchange.h* file.

After creating the converter, data exchange is performed by calling the converter's methods. Converter methods (deprecated, it is recommended to use :blue:`ImportFromFile`\(), :blue:`ImportFromBuffer`\(), :blue:`ExportInfoFile`\(), :blue:`ExportInfoBuffer`\()):


.. code-block:: cpp

   MbeConvResType SATRead( IConvertorProperty3D & property,
                           ItModelDocument &      document,
                           std::iostream *        stream,
                           IProgressIndicator *   indicator = 0 );


.. code-block:: cpp

   MbeConvResType SATWrite( IConvertorProperty3D & property,
                            ItModelDocument &      document,
                            std::iostream *        stream,
                            IProgressIndicator *   indicator = 0 );


.. code-block:: cpp

   MbeConvResType SATRead( IConvertorProperty3D & property,
                           ItModelDocument &      document,
                           IProgressIndicator *   indicator = 0,
                           MbRefItem *            qeuryStitch = 0 );


.. code-block:: cpp

   MbeConvResType SATWrite( IConvertorProperty3D & property,
                            ItModelDocument &      document,
                            IProgressIndicator *   indicator = 0,
                            MbRefItem *            qeuryStitch = 0 );


.. code-block:: cpp

   MbeConvResType IGSRead( IConvertorProperty3D & property,
                           ItModelDocument &      document,
                           IProgressIndicator *   indicator = 0,
                           MbRefItem *            qeuryStitch = 0 );


.. code-block:: cpp

   MbeConvResType IGSWrite( IConvertorProperty3D & property,
                            ItModelDocument &      document,
                            IProgressIndicator *   indicator = 0,
                            MbRefItem *            qeuryStitch = 0 );


.. code-block:: cpp

   MbeConvResType JTRead( IConvertorProperty3D & property,
                          ItModelDocument &      document,
                          IProgressIndicator *   indicator = 0,
                          MbRefItem *            qeuryStitch = 0 );


.. code-block:: cpp

   MbeConvResType JTWrite( IConvertorProperty3D & property,
                           ItModelDocument &      document,
                           IProgressIndicator *   indicator = 0,
                           MbRefItem *            qeuryStitch = 0 );


.. code-block:: cpp

   MbeConvResType XTRead( IConvertorProperty3D & property,
                          ItModelDocument &      document,
                          IProgressIndicator *   indicator = 0,
                          MbRefItem *            qeuryStitch = 0 );


.. code-block:: cpp

   MbeConvResType XTWrite( IConvertorProperty3D & property,
                           ItModelDocument &      document,
                           IProgressIndicator *   indicator = 0,
                           MbRefItem *            qeuryStitch = 0 );


.. code-block:: cpp

   MbeConvResType STEPRead( IConvertorProperty3D & property,
                            ItModelDocument &      document,
                            IProgressIndicator *   indicator = 0,
                            MbRefItem *            qeuryStitch = 0 );


.. code-block:: cpp

   MbeConvResType STEPWrite( IConvertorProperty3D & property,
                             ItModelDocument &      document,
                             IProgressIndicator *   indicator = 0,
                             MbRefItem *            qeuryStitch = 0 );


.. code-block:: cpp

   MbeConvResType STLRead( IConvertorProperty3D & property,
                           ItModelDocument &      document,
                           IProgressIndicator *   indicator = 0,
                           MbRefItem *            qeuryStitch = 0 );


.. code-block:: cpp

   MbeConvResType STLWrite( IConvertorProperty3D & property,
                            ItModelDocument &      document,
                            IProgressIndicator *   indicator = 0,
                            MbRefItem *            qeuryStitch = 0 );


.. code-block:: cpp

   MbeConvResType VRMLRead( IConvertorProperty3D & property,
                            ItModelDocument &      document,
                            IProgressIndicator *   indicator = 0,
                            MbRefItem *            qeuryStitch = 0 );


.. code-block:: cpp

   MbeConvResType VRMLWrite( IConvertorProperty3D & property,
                             ItModelDocument &      document,
                             IProgressIndicator *   indicator = 0,
                             MbRefItem *            qeuryStitch = 0 );


.. code-block:: cpp

   MbeConvResType OBJRead( IConvertorProperty3D & property,
                           ItModelDocument &      document,
                           IProgressIndicator *   indicator = 0)


perform import and export of models in SAT, IGES, JT, X_T, STEP, STL, VRML, OBJ (import only) formats respectively.


The input parameters of the methods are:


- **property** -- the converter properties;
- **stream** -- the stream for receiving or writing a model in exchange format;
- **document** -- the document transmitting the geometric model and other information;
- *indicator* -- the indicator of the reading or writing process progress;
- *qeuryStitch* -- the surface stitching or units of measurement requester during import (deprecated parameter, its use is not recommended, to control stitching you should use the converter properties).


If successful, the methods return *cnv_Success* or *cnv_PartialSuccess*, otherwise the methods return the operation result code from the :ref:`MbResultType <MbResultType>` enumeration.

Upon completion of work, the obtained converter instance must be deleted.

The converter inherits the interface of the :blue:`IConverter3D` class, which is declared in the *conv_model_exchange.h* file.

The following methods are defined in the :blue:`IConverter3D` class:

- Method

  .. code-block:: cpp 

     virtual void SetConfigurationSelector( SPtr<IConfigurationSelector> configuration_selector )

  sets the handler for selecting configurations. If the handler is set and there is more than one configuration (execution) in the imported file, then during the reading process the installed handler will be called to select the required configuration. (see :ref:`Model Configuration Import <Model_Configuration_Import_>`).

  The input parameter **configuration_selector** is a pointer to the handler being set.

- Method

  .. code-block:: cpp

     virtual void SetMetadataTransferCallback( SPtr<IConverterMetadataReceiver> metadataTransferCallback )

  sets the metadata transfer (see :ref:`Import of Construction Format Metadata <Import_of_Construction_Format_Metadata_>`). 

- Method

  .. code-block:: cpp

   virtual MbeConvResType LoadForeignReader( const c3d::path_string &            pluginName,
                                             const c3d::optionNameValuePairs_t & pluginSpecificSettings )


  loads a plugin for obtaining data to build a model. Used for explicitly specifying the plugin to be used for importing proprietary formats, located at the specified path. This is an alternative method to c3d:::blue:`ImportFromFile`\() for using plugins, when the path to the plugins is not explicitly set, assuming that the plugins are located in the same directory as the kernel.

  Input parameters:

  - **pluginName** -- the name of the plugin file;
  - **pluginSpecificSettings** -- the plugin-specific settings (a description of the plugin-specific settings should be obtained from the component provider).

- Method

  .. code-block:: cpp

     virtual MbeConvResType ReleaseForeignReader()

  disconnects the loaded plugin for obtaining data to build a model.

- Method

  .. code-block:: cpp

     virtual MbeConvResType ImportForeign( const c3d::path_string &    path,
                                                 ItModelDocument &     idoc,
                                                 IConvertorProperty3D* prop = 0,
                                                 IProgressIndicator*   indicator = 0 )


  reads a file using the plugin specified in :blue:`LoadForeignReader`\().

  Input parameters:

  - **path** -- the path to the file to be read;
  - **idoc** -- the implementation of the document interface;
  - **prop** -- the implementation of the converter properties interface;
  - **indicator** -- the process progress indicator.