================
Importing models
================

At this point, the application has been initialized, the rendering system has been connected to the window, and our view hierarchy is ready. Now, let's load a model and get it on the screen. Before we begin, you should be aware that HNP can load two types of models - those with embedded CAD data and those without. In the case of CAD models, the HOOPS Exchange library is used. Those file formats, and the type of data Exchange can read from each of them are enumerated in the `Exchange documentation <https://docs.techsoft3d.com/exchange/latest/build/overview.html>`_. In this context, a CAD model is one with metadata associated with it (as opposed to just geometry) such as B-rep, filters, configurations, PMI, etc. Supported non-CAD file types are listed `here <https://docs.techsoft3d.com/hps/latest/build/misc/supported_file_formats.html>`_ and contain geometry only.

Importing a CAD model is as simple as calling `HPS::Exchange::File::Import <https://docs.techsoft3d.com/hps/latest/build/api_ref/cpp/class_h_p_s_1_1_exchange_1_1_file.html#ae24a07e42193dccfdd3a261d2bfc174e>`_ with a filename and an appropriate `HPS::Exchange::ImportOptionsKit <https://docs.techsoft3d.com/hps/latest/build/api_ref/cpp/class_h_p_s_1_1_exchange_1_1_import_options_kit.html>`_. The options kit is where you specify all the various settings related to the file you want to import. For example, if you want to make sure B-rep and tessellation are imported with the model, you would make that setting in this way:

.. literalinclude:: /source/CHPSDoc.cpp
	:language: cpp
	:start-after: //! [import_options]
	:end-before: //! [import_options]
	
You can even get the file format before the import takes place using the following call. This is important because not all options are supported by all file types, and some options *must* be set for certain formats. Therefore, the options you set will depend on what kind of file you're about to load:

.. literalinclude:: /source/CHPSDoc.cpp
	:language: cpp
	:start-after: //! [file_format]
	:end-before: //! [file_format]
	
The options kit is then passed to ``Import``:

.. literalinclude:: /source/CHPSDoc.cpp
	:language: cpp
	:start-after: //! [exchange_import]
	:end-before: //! [exchange_import]
	
Notice in this code snippet, we are making use of a `HPS::Exchange::ImportNotifier <https://docs.techsoft3d.com/hps/latest/build/api_ref/cpp/class_h_p_s_1_1_exchange_1_1_import_notifier.html>`_. This object is used to inform us of the status of the import and the eventual result. Other useful information provided by the `ImportNotifier <https://docs.techsoft3d.com/hps/latest/build/api_ref/cpp/class_h_p_s_1_1_exchange_1_1_import_notifier.html>`_ are status conditions such as unsupported file versions, file not found, file pending import, and others, including eventual success. In our sandbox import function, we can see exactly that logic happening here when we check for ``IOResult.Success``:

.. literalinclude:: /source/CHPSDoc.cpp
	:language: cpp
	:start-after: //! [import_notifier]
	:end-before: //! [import_notifier]
	
In the sandbox, we are using a modal dialog which tracks model progress and waits until the file is completely loaded. However, in your application, that may not be the case. Models are typically loaded asynchronously, therefore, it is important to know when the file is done loading so that we can take action. We can be assured that the model is finished by calling the `Wait() <https://docs.techsoft3d.com/hps/latest/build/api_ref/cpp/class_h_p_s_1_1_i_o_notifier.html#ae200815822662b0936a6b7202191fe51>`_ function. When the function returns, we know HNP has finished its operation::

	notifier.Wait();

A reference to the CAD model itself is provided by the notifier as well, using `notifier.GetCADModel() <https://docs.techsoft3d.com/hps/latest/build/api_ref/cpp/class_h_p_s_1_1_exchange_1_1_import_notifier.html#a989a6c64eef3f9c406effd091f8e69c7>`_. This object is then attached to the `HPS::Model <https://docs.techsoft3d.com/hps/latest/build/api_ref/cpp/class_h_p_s_1_1_model.html>`_ object, which means it is now in the rendering pipeline and will be drawn upon the next update. This code is from *CProgressDialog.cpp*, which gives a visual indication of model loading progress as well as attaches the model to the `HPS::Model <https://docs.techsoft3d.com/hps/latest/build/api_ref/cpp/class_h_p_s_1_1_model.html>`_ object once it's done loading:

.. literalinclude:: /source/CProgressDialog.cpp
	:language: cpp
	:start-after: //! [attach_model]
	:end-before: //! [attach_model]

Importing a non-CAD model is exactly the same process, except instead of using `HPS::Exchange::File::Import <https://docs.techsoft3d.com/hps/latest/build/api_ref/cpp/class_h_p_s_1_1_exchange_1_1_file.html#ae24a07e42193dccfdd3a261d2bfc174e>`_ to load the model, you would use one of the ``HPS::<namespace>::File::Import`` variants. Although this type of model contains geometry only, you can still select certain options in a corresponding import options kit, such as ``HPS::STL::ImportOptionsKit`` or `HPS::Stream::ImportOptionsKit <https://docs.techsoft3d.com/hps/latest/build/api_ref/cpp/class_h_p_s_1_1_stream_1_1_import_options_kit.html>`_.


Component hierarchy
-------------------

HOOPS Visualize uses a generic component hierarchy to represent third-party CAD models which feature topological entities. The component hierarchy is a way to organize the scene graph uniformly across disparate file formats. It also provides developers the ability to extend the capabilities of our importers, as well as to create entirely new importers in a way that is compatible with the Visualize scene graph. Our importers produce CADModel objects that abstract the structure of the model into a component hierarchy as shown below:

.. image:: images/component_hierarchy_generalized.png

Before working with CAD models in your own application, make sure to read and understand the `Component hierarchy <https://docs.techsoft3d.com/hps/latest/build/prog_guide/0904_component_hierarchy.html>`_ section of the HOOPS Visualize Programming Guide.