#####################
Converter Application
#####################

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

   xml-batch-conversion
   stream-cache-workflows
   html-export
   external_data/exchange-sc-mapping
   external_data/xml-assembly-tree


HOOPS Converter converts CAD models into the :doc:`Stream Cache </prog_guide/viewing/data_model/stream_cache/overview>` format used by Communicator to efficiently stream model data to the web client as well as a variety of other output formats. There are many options that control the conversion process. 

Please refer to the list of :doc:`command-line options </api_ref/data_import/converter-command-line-options>`.

HOOPS Converter leverages HOOPS Exchange for file translation. For information on specific file-format reading capabilities, please see the `HOOPS Exchange file formats page <https://docs.techsoft3d.com/exchange/latest/start/supported-formats.html>`_.


.. _cli_license:

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

HOOPS Converter requires a :doc:`valid license </overview/license>` to operate. The license must be provided as a command-line argument every time the converter is run.


Running on Windows
==================

The Windows version of Converter can be run from any directory. This sample can be run from the root directory of the Communicator package:

.. code-block:: none

	authoring\converter\bin\win64\converter.exe --input "authoring\converter\example\_data\GarrettSupportBar4.CATPart" --output_sc "GarrettSupportBar" --license "LICENSE_KEY_GOES_HERE"

If you would prefer to use a text file containing your license key (instead of typing it on the command line), the :doc:`--license_file </api_ref/data_import/converter-command-line-options>` option is also available:

.. code-block:: none
	
	authoring\converter\bin\win64\converter.exe --input "authoring\converter\example\_data\GarrettSupportBar4.CATPart" --output_sc "GarrettSupportBar" --license_file my_license.txt


Running in a "Headless" Linux environment
=========================================

Most Linux-based servers are not set up for 3D graphics rendering by default. Many operations, such as converting certain types of files and creating PNG images, require that an X server and additional graphics libraries are available. The recommended approach for using HOOPS Converter on Linux servers without graphics hardware is to utilize `Xvfb <https://en.wikipedia.org/wiki/Xvfb>`_. The steps below illustrate the process to install Xvfb on Ubuntu server. This general process applies to all distributions; however, the exact steps may vary slightly. Please refer to your package manager's listing for the exact package names on your system.

* Install the required packages:

.. code-block:: none

	sudo apt-get update
	sudo apt-get install xvfb libsdl1.2-dev

* After installation, ``hoops_converter`` should be invoked using ``xvfb-run``. The example below shows how to generate a PNG image:

.. code-block:: none

		/usr/bin/xvfb-run "--auto-servernum" "-s" "-screen 0 640x480x24" /path/to/hoops/converter --license_file
		"/path/to/communicator_license.txt" --input "/path/to/input.file" --output_png "/path/to/output.png"

* In the command line above, the first three parameters are passed to ``xvfb-run``. The next parameter specifies the path to the ``hoops_converter`` executable. All additional parameters are passed to converter.


More examples
=============

The following are examples of command line arguments:

* This will only generate a PNG of the file with the default resolution of 640x480:

.. code-block:: none

	converter --license "LICENSE_KEY_GOES_HERE" --input "c:\temp\Axle.CATPart" --output_png "c:\temp\image.png"

* This will execute Converter with all the commands as listed in *MyConversions.xml*:

.. code-block:: none

	converter --license "LICENSE_KEY_GOES_HERE" --input_xml_batch_file "c:\temp\MyConversions.xml"

Find more examples in the HOOPS Communicator package located at *HOOPS_Communicator/authoring/converter/example/*.


Distributing your application
=============================

64-bit Windows
--------------

To distribute a Windows application using the HOOPS Converter binary (i.e., the file called *converter.exe* in the *authoring\\converter\\bin\\<platform>* folder), the following items must be included with your application:

* All of the binaries contained in the *authoring\\converter\\bin\\<platform>* folder
* Visual Studio Redistributables. See the :doc:`Supported Platforms </overview/supported-platforms>` page for versioning information.


64-bit Linux
------------

For 64-bit Linux distributions, simply include all of the contents in this folder:

* *authoring/converter/bin/linux64*
