==========================
HOOPS SketchUp integration
==========================

Using the SketchUp HIO component
================================

SketchUp is a 3D modelling application that allows users to create, change, and share 3D models. These 3D models are saved in the *.skp* file format. This format has been gaining widespread adoption within the engineering community. The SketchUp HIO component lets you import SketchUp files into HOOPS Visualize and is available for Microsoft Windows platforms. To use this integration, you must download and install the `SketchUp SDK <https://developer.sketchup.com/en>`_.

The content on this page refers to the new version of the SketchUp HIO component, which is HIO SketchUp from Visualize v20.1 or later. If you are planning to use this component, please note that it is not possible to have both the old and new SketchUp importers on the same HOOPS Visualize installation. To use the HOOPS/HIO component for SketchUp, please follow the steps below:

#. Create a *hio_plugins* directory in your application's working directory.  
#. Copy the *hioskp.hio* file found in *<hoops>/bin/<platform>/hio_plugins/hio_skp* to the *hio_plugins* directory created in the previous step.
#. Ensure that the SketchUp SDK is installed on your system and in your path.
#.  Run your application.

During start-up, when HOOPS/MVO finds the SketchUp HIO component in your application's path, it will perform the following steps:  

#. Load in the necessary SketchUp libraries. 
#. Create the appropriate input handler.
#. Register this handler and the associated file extensions to the HIOManager.

Once the SketchUp HIO component is successfully loaded, your application will be able import SketchUp files without having to recompile HOOPS. To utilize the extensive services available in the SketchUp toolkit, you must compile against the SketchUp libraries directly and follow the steps described in :ref:`Integrating directly with SketchUp <prog_guide/hio/HIO_SketchUpIntegration:Integrating directly with SketchUp>`.


Rebuilding the HIO component
============================

Customers receive the SKP HIO file pre-built with the HOOPS Visualize package. The SketchUp HIO component was built against a specific :doc:`version </general/release_notes/index>` of SketchUp. If you want your application to run against another version of SketchUp, you must rebuild the SketchUp HIO component with that version of the library. Note that you may face some obstacles building against a different version of the SketchUp if interfaces are not compatible with the original libraries that the HIO component was built against.

To rebuild, open the *hio_skp_<version>.vcxproj* project located in the *<hoops>/Dev_Tools/hoops_hio/hio_skp/source*. Be sure to set the environment variable ``SKP_SDK_INSTALL_DIR`` to point to the root of your SketchUp installation before you begin building. The project creates a *.hio* file. 


Supported entities
==================

HOOPS supports a variety of SketchUp entities. The following list names the supported entities.

* Group
* Components definition
* Component Instance
* Faces
* Edges
* Curves
* Texture
* Material
* Surfaces
* FreeHand Curves
* Attributes as User Options
* Metadata
* Layers (see below)

Not supported:

* Animation
* Text
* Dimension
* Font


Special notes regarding layers
------------------------------

The importer is able to read geometry assigned to a layer, however, layers themselves as a concept are not imported. Thus, associations between layers and geometric data are lost. Visibility settings for geometry which were present on the active layer at the time the model was saved will be used for those entities when loaded by HOOPS Visualize.


SKP units and NamedOptions
===========================

The units and ``NamedOptions`` are imported as user options in a segment called "model_information", which will be created as a subsegment of the segment where the model is imported. All ``NamedOptions`` will be present as key-value pairs.

There will also be two user options pertaining to units in that segment. One is called "length unit" and its value can be one of the following:

* inches
* feet
* millimeters
* centimeters
* meters
* undefined

The second one is called "length format" and its value can be one of thefollowing:

* decimal
* architectural
* engineering
* fractional
* undefined

Developers interested in obtaining further details about the original SKP units properties should refer to the SKP format documentation included in the SketchUp SDK available from Trimble.


Input handler options
=====================

Within HOOPS/MVO, a number of options are available to facilitate the importing process. Specifically for SketchUp, you will find two options for ``HInputHandlerOptions``. The first, ``m_bIgnoreOffEntity``, gives you control over whether invisible entities should be imported into HOOPS Visualize. If the ``m_bIgnoreOffEntity`` option is set to ``true``, Visualize will not import invisible entities. Enabling this option can save time during loading if the invisible entities won't be needed. The default for this option is false.

The second option, ``m_bImportMetadata``, causes the importer to collect all metadata for a model and insert it in a segment called "model_metadata" in the form of a user option. The "model_metadata" segment is directly below the segment where you imported the model. Metadata is always presented in key-value pairs.

For example, if you see a user option with this value::

	"LastEditedBy = Amerigo, BackgroundColor = red"

...you can interpret the keys to be "LastEditedBy" and "BackgroundColor", and the values to be "Amerigo" and "red", respectively.

The following sample code shows to set options for the ``HIOUtilitySKP`` input handler::

	HInputHandlerOptions skp_input_options;
	 
	// set m_bIgnoreOffEntity to true so that HOOPS will not import invisible entities
	skp_input_options.m_bIgnoreOffEntity = true;
		
	// import metadata
	skp_input_options.m_bImportMetadata = true;
		
	// setting the view is required!
	skp_input_options.m_pHBaseView = view;
		
	view->GetModel()->Read(FileName, view, true, &skp_input_options);


Integrating directly with SketchUp
==================================

If you want to use the full range of the SketchUp SDK services, the SketchUp HIO component may not be suitable. Instead, you should integrate directly with SketchUp. First, please ensure that the SketchUp SDK is installed and in your application's path. Then, follow these steps below:

1. Add all *.h* and *.cpp* files located in *<hoops>/Dev_Tools/hoops_hio/hio_skp/source* to your project.

2. Copy the file *<SKP_SDK_INSTALL_DIR>/binaries/x64/slapi.lib* to your HOOPS *bin* directory: *<HOOPS_INSTALL_DIR>/bin/<PLATFORM>*.
	
3. Add following directory paths to your additional include folders list:

	* *<HOOPS_INSTALL_DIR>/Dev_Tools/hoops_3dgs/source*
	* *<HOOPS_INSTALL_DIR>/Dev_Tools/hoops_mvo/source*
	* *<HOOPS_INSTALL_DIR>/Dev_Tools/utility/source*

4. Add 'HIO_SKP' to your preprocessor definition list.
	
5. Add *hoops_utilsstatd_md.lib*, *hoops_mvo_mgkd.lib*, and *hoopsd.lib* as additional dependencies.
	
6. Add following directory paths to your additional library folders' list:

	* *<HOOPS_INSTALL_DIR>/Dev_Tools/hoops_3dgs/lib/<PLATFORM>*
	* *<HOOPS_INSTALL_DIR>/Dev_Tools/hoops_mvo/lib/<PLATFORM>*
	* *<HOOPS_INSTALL_DIR>/Dev_Tools/utility/lib/<PLATFORM>*

Once you have completed the above steps, you do not need to rely on the SketchUp HIO component anymore. Please remove the associated *.hio* file from the *hio_plugins* directory in your application's working directory. Note that in a direct integration, you must register ``HIOUtilitySKP`` via ``HIOManager::RegisterInputHandler`` so that the ``HBaseModel::Read`` function can recognize that the *.skp* file format is supported. For more information on HOOPS/MVO file input/output architecture, please see the section :doc:`File Input/Output and the I/O Manager </prog_guide/mvo/04_hio_manager>` of the HOOPS/MVO Programming Guide.

You should now be able to read SKP Files in your application with code similar to this::

	HIOUtilitySKP skp_reader;
	HInputHandlerOptions skp_opt;
	skp_opt.m_pHBaseView = view;
	HFileInputResult result = skp_reader.FileInputByKey("myFile.skp", &skp_opt);
