#################
Converter Library
#################

The Converter library is a C++ library which exposes the rich functionality of Converter, and makes it easy to embed CAD-File conversion into your application.

.. toctree::
   :maxdepth: 1
   :caption: Table of Contents

   conversion-examples


License key
===========

The HOOPS Converter Library requires a :doc:`valid license </overview/license>` to operate.


Linking to the Converter library
================================

The Converter library requires *libconverter.lib* to be included in your application and requires *libconverter.dll* or *libconverter.so* to be available in your system path. Additionally, *libconverter* has a dependency on all dll/so files in the converter *bin/* directory, so they need to be in the same folder that your application resides in.

.. note::

	For more information on the location of these files in your HOOPS Communicator package, consult our :doc:`Package Description </overview/package-description>` page.


Customizing Converter
=====================

The Converter library is available for Windows platforms.

Developers can customize their own Converter application when they want to integrate it other toolkits, for example, when using HOOPS Visualize or Exchange. Let's start by opening *sample_projects.sln* found in *<COMMUNICATOR_INSTALL_DIR>/authoring/converter/example/sample_projects*. There two projects here - *demo_converter* and *mini_converter*.

Both projects are using *libconverter.dll* under the hood and demonstrate how to generate a PNG or Stream Cache file. 

demo_converter
--------------

The project *demo_converter* is set up to parse character identifiers in the command arguments to run the conversion. Let's run through an example:

1. Open a text editor, and paste the following:

.. code-block:: none

	-t png -l "your_license" "../../_data/MountainHome.u3d" "../../_data/test.png"
	
The format of the text follows this pattern: a) options in the front, b) the second to last parameter is the input file, and c) the last is the output. More option identifiers can be found in the file *Command.cpp* included in the *Source Files* folder of the Visual Studio project.

2. Delete the text "your_license" and replace with a valid HOOPS license string. Now copy the entire line of text.

3. In Visual Studio, right-click *demo_converter* and select *Properties*.

4. In *Configuration Properties → Debugging → Command Arguments*, paste the text in this field.

5. Build and run the project. Check to make sure that the PNG was generated in *<COMMUNICATOR_INSTALL_DIR>/authoring/converter/example/_data*.


mini_converter
--------------

The *mini_converter* project also uses *libconverter.dll*, but it is even more streamlined than *demo_converter*. The converter options need to be selected via libconverter classes such as ``SC_Import_Options`` or ``SC_Export_Options``.  The aforementioned class objects can be found in the project file *mini.cpp*.

1. Open a text editor and copy and paste the following:

.. code-block:: none

	"your_license" "../../_data/MountainHome.u3d" "../../_data/test_sc"
	
The format of the text follows this pattern: a) license in the front, followed by b) the input file, and ends with c) the output.

2. Delete the text "your_license" and replace it with a valid HOOPS license string. Now, copy the entire text.

3. Right-click *mini_converter* and select *Properties*.

4. In Configuration Properties → Debugging → Command Arguments, paste the text in this field.

5. Build and run the project. Check to make sure that the Stream Cache file was generated in *<COMMUNICATOR_INSTALL_DIR>/authoring/converter/example/_data*.


Example usage
=============

The following example generates a Stream Cache Instance from a single input file:
	
.. code-block:: cpp

	Communicator::Converter converter;
	converter.Init(your_license_key);
	Communicator::Importer importer;
	Communicator::SC_Import_Options importOptions;
	importer.Init(&converter);
	if (!importer.Load(path_to_your_model_file, importOptions))
	{
	  // handle error
	}
	  
	Communicator::Exporter *exporter = new Communicator::Exporter();
	exporter->Init(&importer);
	Communicator::SC_Export_Options exportOptions;
	exporter->WriteSC(path_to_your_sc_folder, nullptr, exportOptions);

	
Importing multiple files
========================

A single ``Importer`` object should be used for importing all files during the life of your application.  Attempts to create additional importer objects will result in an exception being thrown.

For more detailed examples of Converter library usage, please see the :doc:`conversion examples </prog_guide/data_import/cad_conversion/converter_lib/conversion-examples>` page, or the *HOOPS_Communicator/authoring/converter/example/* directory of the HOOPS Communicator package.
