.. role:: blue
   :class: blue

Порядок работы с конвертером
=============================
.. _How_to_Work_with_the_Converter:

Конвертеры предоставляют средства для экспорта и импорта моделей :blue:`MbModel`, :blue:`MbItem` и пользовательских реализаций документов :blue:`ItModelDocument`.

Группа функций, предназначенных для обмена данными через файлы, размещена в файле *conv_model_exchange.h* и объявлена в пространстве имён c3d:

Функция

.. code-block:: cpp

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

позволяет прочитать файл обменного формата в модель.

Функция

.. code-block:: cpp

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

позволяет прочитать файл обменного формата в элемент.

Функция

.. code-block:: cpp

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

позволяет прочитать файл обменного формата в модель.

Функция

.. code-block:: cpp

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

позволяет записать модель в файл обменного формата.

Функция

.. code-block:: cpp

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

позволяет записать элемент в файл обменного формата.

Функция

.. code-block:: cpp

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

позволяет записать модельный документ в файл обменного формата.

Аргументами функций являются:

- **model** -- экспортируемая или импортируемая геометрическая модель;
- **item** -- элемент модели;
- **mDoc** -- модельный документ;
- **fileName (filePath)** -- полный путь к файлу;
- *prop* -- реализация интерфейса свойств конвертера;
- *indicator* -- индикатор прогресса.

При импорте обменный формат определяется на основе расширения файла.

Группа функций, реализующих передачу моделей в обменные форматы через оперативную память:

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

Аргументами функций являются:

- **model** -- экспортируемая или импортируемая геометрическая модель;
- **item** -- элемент модели;
- **mDoc** -- модельный документ;
- **modelFormat** -- формат обменного файла;
- **buffer** -- буфер;
- **data** -- адрес буфера в памяти;
- *prop* -- настройки конвертера;
- *indicator* -- индикатор прогресса.

Функции :blue:`ImportFromFile`\(), :blue:`ImportFromBuffer`\() выполняют импорт геометрических моделей:

-- форматов STL, OBJ;

-- формата SAT/SAB до 22.0 версии включительно;

-- формата IGES версии 5.3;

-- формата JT версий 8.0 — 11.x;

-- формата Parasolid до версии 25.0 включительно;

-- формата STEP с поддерживаемыми прикладными протоколами 203, 214;

-- формата VRML версии 2.0.

Функции :blue:`ExportIntoFile`\(), :blue:`ExportInfoBuffer`\() выполняют экспорт геометрических моделей:

-- форматов STL, OBJ;

-- формата SAT/SAB до 22.0 версии включительно;

-- формата IGES версии 5.3;

-- формата JT версии 9.5;

-- формата Parasolid до версии 10.0 включительно;

-- формата STEP с поддерживаемыми прикладными протоколами 203, 214;

-- формата VRML версии 2.0.

Результат :blue:`FullFilePath`\() аргумента *prop* используется для определения формата обменного файла только в том случае, если значение modelFormat равно *mxf_autodetect*.

Ответственность за удаление буфера, который создаёт и наполняет функция :blue:`ExportIntoBuffer`\(), лежит на пользователе. Для освобождения памяти рекомендуется использовать оператор *delete*\[].

Другим способом импорта и экспорта модели является обращение к методам конвертера :blue:`IConverter3D`.

Для начала работы с конвертером необходимо получить его экземпляр. Определённая в глобальной области видимости функция IConverter3D * :blue:`GetConvertor3D`\() создает конвертер, который может выполнять импорт и экспорт моделей в любом из поддерживаемых форматов. Функция не имеет параметров. В случае успеха функция возвращает конвертер, в противном случае возвращает нулевой указатель.

Функция объявлена в файле *conv_model_exchange.h*.

После создания конвертера обмен данными осуществляется путем вызова методов конвертера. Методы конвертера (устаревшие, рекомендуется использовать :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)

выполняют импорт и экспорт модели в форматах SAT, IGES, JT, X_T, STEP, STL, VRML, OBJ (только импорт) соответственно.

Входными параметрами методов являются:

- **property** -- свойства конвертера;
- **stream** -- поток для получения или записи модели обменного формата;
- **document** -- документ, передающий геометрическую модель и другую информацию;
- *indicator* -- индикатор хода процесса чтения или записи;
- *qeuryStitch* -- запросчик сшивки поверхностей или единиц измерения при импорте (устаревший параметр, не рекомендуется использовать, для управления сшивкой следует пользоваться свойствами конвертера).

В случае успеха методы возвращают *cnv_Success* или *cnv_PartialSuccess*, в противном случае возвращается код результата операции из перечисления :ref:`MbResultType <MbResultType>`.

По окончании работы полученный экземпляр конвертера необходимо удалить.

Конвертер наследует интерфейс класса :blue:`IConverter3D`, который объявлен в файле *conv_model_exchange.h*.

В классе :blue:`IConverter3D` определены следующие методы:

- Метод

  .. code-block:: cpp 

     virtual void SetConfigurationSelector( SPtr<IConfigurationSelector> configuration_selector )

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

  Входной параметр **configuration_selector** -- указатель на устанавливаемый обработчик.

- Метод

  .. code-block:: cpp

     virtual void SetMetadataTransferCallback( SPtr<IConverterMetadataReceiver> metadataTransferCallback )

  устанавливает передачу метаданных (см. :ref:`Импорт метаданных строительных форматов <Import_of_Construction_Format_Metadata>`).  

- Метод

  .. code-block:: cpp

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

  загружает плагин получения данных для построения модели. Используется для явного задания используемого плагина для импорта проприетарных форматов, расположенного по указанному пути. Это альтернативный методу c3d:::blue:`ImportFromFile`\() метод использования плагинов, когда путь до плагинов явно не задается, предполагая, что плагины лежат в одном каталоге с ядром.

  Входные параметры:

  - **pluginName** -- имя подключаемого файла;
  - **pluginSpecificSettings** -- специфические для плагина настройки (описание специфичных для плагина настроек следует получить у поставщика компонента).

- Метод

  .. code-block:: cpp

     virtual MbeConvResType ReleaseForeignReader()

  отключает загруженный плагин получения данных для построения модели.

- Метод

  .. code-block:: cpp

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

  читает файл с использованием плагина, заданного в :blue:`LoadForeignReader`\().

  Входные параметры:

  - **path** -- путь к файлу, который нужно прочитать;
  - **idoc** -- реализация интерфейса документа;
  - **prop** -- реализация интерфейса свойств конвертера;
  - **indicator** -- индикатор хода процесса.