########################
File-to-File Translation
########################

This tutorial walks you through the ``ImportExport`` sample, one of the :doc:`samples </sample_codes>` included with HOOPS Exchange.
The sample demonstrates the basic workflow of reading an input file and exporting it to a new format.

As a prerequisite, ensure you have followed the previous tutorial about :doc:`Set Up Your Environment </tutorials/c/environment-setup>`.
Ensure you can build and run the ``ImportExport`` sample. The sample code can be found in the ``samples/hello_world/ImportExport`` folder of your package.

The Code
========

Open ``ImportExport.cpp`` in your editor.
The sample is organized into four functions that represent the typical HOOPS Exchange workflow:

.. code-block:: c

   static void initialize_exchange(void);
   static A3DAsmModelFile* import_cad_file(const std::string& file_path);
   static void export_cad_file(A3DAsmModelFile* model_file, const std::string& file_path);
   static void terminate_exchange(void);

The ``main()`` function calls these in sequence: initialize, import, export, and terminate.

For a detailed walkthrough of the full implementation, see the :doc:`/examples/import_export` example documentation.

Initialization and Termination
------------------------------

Before using HOOPS Exchange, you must load the library and apply your license.
The ``initialize_exchange()`` function handles this:

.. literalinclude:: /../../../final-package/samples/hello_world/ImportExport/ImportExport.cpp
   :lines: 50-62
   :linenos:
   :lineno-match:
   :emphasize-lines: 2, 5, 8

The three key calls are :c:func:`A3DSDKLoadLibraryA`, :c:func:`A3DLicPutUnifiedLicense`, and :c:func:`A3DDllInitialize`.

When finished, ``terminate_exchange()`` cleans up:

.. literalinclude:: /../../../final-package/samples/hello_world/ImportExport/ImportExport.cpp
   :lines: 269-274
   :linenos:
   :lineno-match:

Importing
---------

The ``import_cad_file()`` function configures import parameters and calls :c:func:`A3DAsmModelFileLoadFromFile`:

.. literalinclude:: /../../../final-package/samples/hello_world/ImportExport/ImportExport.cpp
   :lines: 77-78, 80-85, 94, 100-105
   :linenos:
   :lineno-match:
   :emphasize-lines: 10-13

The :c:struct:`A3DRWParamsLoadData` structure controls what gets loaded: geometry types, PMI, attributes, tessellation quality, and more.

Exporting
---------

The ``export_cad_file()`` function writes the model to a new format.
Each format has its own export function and parameters structure. Here's the STEP export case:

.. literalinclude:: /../../../final-package/samples/hello_world/ImportExport/ImportExport.cpp
   :lines: 141-145
   :linenos:
   :lineno-match:
   :emphasize-lines: 3

The sample determines the output format from the file extension and calls the appropriate export function.

The Main Flow
-------------

The ``main()`` function ties everything together:

.. literalinclude:: /../../../final-package/samples/hello_world/ImportExport/ImportExport.cpp
   :lines: 293-301
   :linenos:
   :lineno-match:
   :emphasize-lines: 3-7

Running the Sample
------------------

If you run the program without arguments, defaults are used:

- **Input:** ``samples/data/catiaV5/CV5_Aquo_Bottle/_Aquo Bottle.CATProduct``
- **Output:** the input filename with ``.prc`` appended

Use ``--help`` to see all available options


Playing With The Sample
=======================

In this section we will tweak the code and see the changes.

.. tabs::

   .. group-tab:: Windows

      **Change the command line**
    
      In Visual Studio from the Solution Tree explorer:

         * Locate the sample ``ImportExport``
         * Right click on it and select *Properties*.
         * Edit the *Command Argument* setting under the Debugging tab to change the input CAD file and output.

         Assuming that the HOOPS Exchange API package is installed on the root of your disk ``C:`` the command argument looks like this:
         
         ``"C:\<HOOPS_EXCHANGE_INSTALL_DIR>\samples\data\catiaV5\CV5_Aquo_Bottle\Bullet_Lid_Cap.CATPart" "C:\<HOOPS_EXCHANGE_INSTALL_DIR>\samples\data\catiaV5\CV5_Aquo_Bottle\Bullet_Lid_Cap.CATPart.stl"``

         .. image:: /_assets/images/vs-test-sample.png
            :width: 50%
            :align: center
            
         
         * *Run* the sample ``ImportExport`` to convert a CATIA V5 part called **Bullet_Lid_Cap.CATPart** to STL format.
         * Locate the file *Bullet_Lid_Cap.CATPart.stl* in your output folder.
         * Open the *HOOPS Demo Viewer* desktop application and and *drag & drop* your resulting **Bullet_Lid_Cap.CATPart.stl** file to quickly visualize the part:
    
         .. image:: /_assets/images/Bullet_Lid_Cap.CATPart-win.png
            :width: 50%
            :align: center

         
         You just have learned how to specify your own input CAD file and Output format.
      
      **Change the conversions settings**    
      
      In Visual Studio from the Solution Tree explorer:

         * Locate the sample ``ImportExport``
         * Under the Debugging tab edit the *Command Argument* setting to specify the input CAD file and output.

      Assuming that the HOOPS Exchange API package is installed on the root of your disk ``C:`` the command argument looks like this:

      ``"C:\<HOOPS_EXCHANGE_INSTALL_DIR>\samples\data\pmi\PMI_Sample\CV5_Sample.CATPart" "C:\<HOOPS_EXCHANGE_INSTALL_DIR>\samples\samples\data\pmi\PMI_Sample\CV5_Sample.CATPart.prc"``

         
         * *Run* the sample to convert the file **CV5_Sample.CATPart** to PRC format.
         * Locate and *drag & drop* the resulting **CV5_Sample.CATPart.prc** in *HOOPS Demo Viewer* to visualize the part in your output folder:
         
         .. image:: /_assets/images/pmi-sample.png
            :width: 50%
            :align: center


         * Open ``ImportExport.cpp`` in Visual Studio.

         In the ``import_cad_file()`` function, you'll find all the import parameters. Let's modify one:

         * Locate the line ``read_params.m_sGeneral.m_bReadPmis = A3D_TRUE;``
         * Change it to ``read_params.m_sGeneral.m_bReadPmis = A3D_FALSE;``
         * *Rebuild* and *Run* the sample to convert the file **CV5_Sample.CATPart** to PRC format again.
         * Locate and *drag & drop* the resulting **CV5_Sample.CATPart.prc** in *HOOPS Demo Viewer* to visualize the part.
         * Compare the two resulting **CV5_Sample.CATPart.prc** files.

         .. image:: /_assets/images/pmi-sample-no-pmi.png
            :width: 50%
            :align: center

      As you can see, by turning off the import parameter ``m_bReadPmis``, the *Product and Manufacturing Information* is not loaded or converted.
         
   .. group-tab:: Linux

      **Change the command line**
            
      On Linux, open the *Terminal*:
      
         * Locate the sample ``ImportExport`` from the installation folder ``..\samples\hello_world\ImportExport``
         * Right click on the folder and select *Open in Terminal*
         * Locate the file **Bullet_Lid_Cap.CATPart** from the installation folder ``..\samples\data\catiaV5\``
         * Make sure the Sample is already built otherwise build it again. Command Line: ``make``
                  
         .. image:: /_assets/images/Import_export_make.png
            :width: 50%
            :align: center                 
                  
         * *Run* the sample ``ImportExport`` to convert a CATIA V5 part called **Bullet_Lid_Cap.CATPart** to STL format. Command Line ``./ImportExport ../samples/data/catiaV5/Bullet_Lid_Cap.CATPart ../samples/data\/atiaV5/Bullet_Lid_Cap.CATPart.stl``
                  
         .. image:: /_assets/images/Import_export_make_run.png
            :width: 50%
            :align: center
            
         * *Run* the sample ``Viewer`` to load the resulting part called **Bullet_Lid_Cap.CATPart.stl**. Command Line ``./Viewer ../samples/data/catiaV5/Bullet_Lid_Cap.CATPart.stl``
         * **Bullet_Lid_Cap.CATPart.stl** file will be displayed in an OpenGL Windows:
            
         .. image:: /_assets/images/Bullet_Lid_Cap.CATPart-linux.png
            :width: 50%
            :align: center
         
      You just have learned how to specify your own input CAD file and Output format.
      
      **Change the conversions settings**

         * Stop the execution of the sample ``Viewer`` (Ctrl+C).
         * Locate the file **CV5_Sample.CATPart** from the installation folder ``..\samples\data\pmi\``
         * *Run* the sample ``importExport`` to convert the file **CV5_Sample.CATPart** to PRC format.
         * Locate the resulting **CV5_Sample.CATPart.prc** file from the folder ``./samples/data/pmi/``
         * *Run* the sample ``Viewer`` to load the PRC file. Command Line ``./Viewer ../samples/data/pmi/CV5_Sample.CATPart.prc``
         
         .. image:: /_assets/images/pmi-sample-linux.png
            :width: 50%
            :align: center

         * Stop the execution of the sample ``Viewer`` (Ctrl+C).
         * Open ``ImportExport.cpp`` in your text editor.

      In the ``import_cad_file()`` function, you'll find all the import parameters. Let's modify one:

         * Locate the line ``read_params.m_sGeneral.m_bReadPmis = A3D_TRUE;``
         * Change it to ``read_params.m_sGeneral.m_bReadPmis = A3D_FALSE;``
         * *Rebuild* with ``make clean`` then ``make``
         * *Run* the sample to convert **CV5_Sample.CATPart** to PRC format again.
         * *Run* the sample ``Viewer`` to load the PRC file: ``./Viewer ../samples/data/pmi/CV5_Sample.CATPart.prc``
         * Compare the two resulting **CV5_Sample.CATPart.prc** files.

         .. image:: /_assets/images/pmi-sample-no-pmi-linux.png
            :width: 50%
            :align: center

      As you can see, by turning off the import parameter ``m_bReadPmis``, the *Product and Manufacturing Information* is not loaded or converted.

   .. group-tab:: macOS
   
      **Change the command line**
      
      On macOS, open the *Terminal*:
      
         * Locate the sample ``ImportExport`` from the installation folder ``..\samples\hello_world\ImportExport``
         * Right click on the folder and select *Open in Terminal*.
         * Locate the file **Bullet_Lid_Cap.CATPart** from the installation folder ``..\samples\data\catiaV5\``
         * Make sure the Sample is already built otherwise build it again. Command Line: ``make``
                  
         .. image:: /_assets/images/Import_export_make.png
            :width: 50%
            :align: center                 
                  
         * *Run* the sample ``ImportExport`` to convert a CATIA V5 part called **Bullet_Lid_Cap.CATPart** to STL format. Command Line ``./ImportExport ../samples/data/catiaV5/Bullet_Lid_Cap.CATPart ../samples/data\/atiaV5/Bullet_Lid_Cap.CATPart.stl``
                  
         .. image:: /_assets/images/Import_export_make_run.png
            :width: 50%
            :align: center
            
         * *Run* the sample ``Viewer`` to load the resulting part called **Bullet_Lid_Cap.CATPart.stl**. Command Line ``./Viewer ../samples/data/catiaV5/Bullet_Lid_Cap.CATPart.stl``
         * **Bullet_Lid_Cap.CATPart.stl** file will be displayed in an OpenGL Windows:
            
         .. image:: /_assets/images/Bullet_Lid_Cap.CATPart-mac.png
            :width: 50%
            :align: center
         
      You just have learned how to specify your own input CAD file and Output format.
      
      **Change the conversions settings**

         * Stop the execution of the sample ``Viewer`` (Ctrl+C).
         * Locate the file **CV5_Sample.CATPart** from the installation folder ``..\samples\data\pmi\``
         * *Run* the sample ``importExport`` to convert the file **CV5_Sample.CATPart** to PRC format.
         * Locate the resulting **CV5_Sample.CATPart.prc** file from the folder ``./samples/data/pmi/``
         * *Run* the sample ``Viewer`` to load the PRC file. Command Line ``./Viewer ../samples/data/pmi/CV5_Sample.CATPart.prc``
         
         .. image:: /_assets/images/pmi-sample-mac.png
            :width: 50%
            :align: center

         * Stop the execution of the sample ``Viewer`` (Ctrl+C).
         * Open ``ImportExport.cpp`` in your text editor.

      In the ``import_cad_file()`` function, you'll find all the import parameters. Let's modify one:

         * Locate the line ``read_params.m_sGeneral.m_bReadPmis = A3D_TRUE;``
         * Change it to ``read_params.m_sGeneral.m_bReadPmis = A3D_FALSE;``
         * *Rebuild* with ``make clean`` then ``make``
         * *Run* the sample to convert **CV5_Sample.CATPart** to PRC format again.
         * *Run* the sample ``Viewer`` to load the PRC file: ``./Viewer ../samples/data/pmi/CV5_Sample.CATPart.prc``
         * Compare the two resulting **CV5_Sample.CATPart.prc** files.

         .. image:: /_assets/images/pmi-sample-no-pmi-mac.png
            :width: 50%
            :align: center

      As you can see, by turning off the import parameter ``m_bReadPmis``, the *Product and Manufacturing Information* is not loaded or converted.
      

   .. group-tab:: iOS
                  
      #. **Build and Run the sample IOSWriter**

         * Launch Xcode and select *Open Existing Project*.
         * In the ``../samples/ios/IOSWriter`` folder of your installed package, open ``IOSWriter.xcodeproj``
         * From the *Project navigator* bar select the file ``ts-0001.stp``
         * Right Click ``Add files to "IOSWriter"...``
         * Build the sample
         * Go to the tab ``Product`` > ``Build For`` > ``Running``
         * Run the sample ``IOSWriter``
         * Go to the tab ``Product`` > ``Run``
      
         .. image:: /_assets/images/IOSWriter.png
            :width: 50%
            :align: center
      
         * The iOS simulator will be launched
         * The file ``ts-0001.stp`` is being converted to XT (Parasolid format)
         * The ``ts-0001.prc.x_t`` file is generated and is available at:
         
         ``/Users/me/Library/Developer/CoreSimulator/Devices/XXXX/data/Containers/Data/Application/XXXX/Documents``
      
         .. image:: /_assets/images/IOSWriterRun.png
            :width: 50%
            :align: center
      
         * Locate the file ``ts-0001.stp.x_t``
         * If you have previously executed HOOPS Exchange on macOS you can re-use the sample Viewer to open your resulting ``ts-0001.prc.x_t`` file export from your iOS emulator:
      
         .. image:: /_assets/images/ios-macos-viewer.png
            :width: 50%
            :align: center
      
      **Change the conversions settings**

         * Open the file ``IOSWriter.cpp`` in Xcode.

      In this file, you'll find the import parameters in the :c:struct:`A3DRWParamsLoadData` structure.
      Import and export parameters can be modified as needed.

         * Open the file ``CADFileViewController.swift`` in Xcode.
         
      You are now looking at the "commands" of the sample IOSWriter
      
         * Change the parameter ``let TYPE_EXPORT = PARASOLID`` to ``let TYPE_EXPORT = IGES``
         * Rebuild* and *Run* the sample.
         * The iOS simulator will be launched
         * The file ``ts-0001.stp`` is being converted to IGES format.
         * The ``ts-0001.stp.igs`` file is generated and is available at:
         
         ``/Users/me/Library/Developer/CoreSimulator/Devices/XXXX/data/Containers/Data/Application/XXXX/Documents``
         
         * Open the ``ts-0001.stp.igs`` file in the macOS Viewer to visualize the part:
      
         .. image:: /_assets/images/ios-macos-viewer-step.png
            :width: 50%
            :align: center
      
            
   .. group-tab:: Android

      Coming soon... 
      

   
Conclusion
==========

The file-to-file workflow is a common starting point for evaluating the capabilities of HOOPS Exchange.
Using the ``ImportExport`` sample that ships with the product, you can easily convert files from one format to another.

By completing this tutorial, you have learned:

- How to initialize and terminate HOOPS Exchange
- How to load a CAD file using :c:func:`A3DAsmModelFileLoadFromFile`
- How to configure import parameters with :c:struct:`A3DRWParamsLoadData`
- How to export to various formats using the format-specific export functions
- How to properly clean up with :c:func:`A3DAsmModelFileDelete`

For more details on import and export options, see the :doc:`/guide/basic_operations/load_model` programming guide.

Now that you have completed the *ImportExport* sample, you are ready to move forward with the :doc:`/tutorials/c/print-assembly-structure` tutorial.

