########
Textures
########

Creating and assigning a texture to a node
==========================================

A common technique to improve the visual appearance of a model and make it look more realistic is the use of textures. Often textures will be part of an imported model but then can also be authored directly through libsc or created on the fly via the HOOPS Web Viewer API.

In this chapter, we will be discussing the various HOOPS Web Viewer API’s for creating and applying textures to a model and the texture options they support.

.. image:: images/textures_building_model.png

Creating a new texture is a two-step process. First, you need to create an image by passing a `UInt8Buffer array <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array>`_ containing the raw image data in one of the :doc:`supported image formats  </api_ref/viewing/enums/Communicator.ImageFormat>` to the :ref:`createImage()  <api_ref/viewing/classes/Communicator.Model:createimage>` function. After the image has been created you can then set it as a texture on a node in the model tree:

.. literalinclude:: /../../applications/client/docs/PG_Viewing_textures.ts
	   :start-after: //! [viewing_createexture]
	   :end-before: //! [viewing_createexture]

The :ref:`createImage() <api_ref/viewing/classes/Communicator.Model:createimage>` function takes a second optional parameter which is called the "thumbnail" image. This should be a low-resolution and uncompressed image which will be used while the main image is decoded. Supplying this thumbnail image only makes sense if the main image is in a format that requires decoding (PNG, JPG).


Sources for image data
======================

There are various ways to retrieve image data in a web browser. Below are two examples.

1. Fetching an image residing on the server via an HTTP Request

.. literalinclude:: /../../applications/client/docs/PG_Viewing_textures.ts
	   :start-after: //! [viewing_httprequestimage]
	   :end-before: //! [viewing_httprequestimage]

In the above example, we download an image called *test.png* via an HTTP request and pass the request.response directly to the :ref:`createImage()  <api_ref/viewing/classes/Communicator.Model:createimage>` function.

2. Fetching an image from a canvas

.. literalinclude:: /../../applications/client/docs/PG_Viewing_textures.ts
	   :start-after: //! [viewing_canvasimage]
	   :end-before: //! [viewing_canvasimage]

In the case above we are converting the content of a canvas to a binary image blob and then use it to create an image and its associated texture in HOOPS Communicator. This approach can be used to apply dynamically generated content (e.g. an SVG JS library rendering into a canvas object) to geometry in the HOOPS Web Viewer.


Removing a texture from a mesh
==============================

To remove a texture from a node you can call :ref:`unsetNodesTexture() <api_ref/viewing/classes/Communicator.Model:unsetnodestexture>`.

.. literalinclude:: /../../applications/client/docs/PG_Viewing_textures.ts
	   :start-after: //! [viewing_unsettexture]
	   :end-before: //! [viewing_unsettexture]


Texture options
===============

When applying a texture to a node with the :ref:`setNodesTexture()  <api_ref/viewing/classes/Communicator.Model:setnodestexture>` functions various options determine how the texture is applied to a mesh. The important ones are the tiling and matrix options which give you a lot of control over how the texture stretches over the surface of the mesh. You can also set the "decal" texture modifier which in combination with supplying a texture with transparent areas combines the texture with the original color of the mesh. This modifier is not currently supported when working with PBR materials.

For more details on ``TextureOptions``, options follow this :ref:`link  <api_ref/viewing/interfaces/Communicator.TextureOptions>`.

.. literalinclude:: /../../applications/client/docs/PG_Viewing_textures.ts
	   :start-after: //! [viewing_scaletexture]
	   :end-before: //! [viewing_scaletexture]

.. image:: images/textures_checkerboard_mesh.png

The above code creates a checkerboard pattern on the mesh by tiling the supplied image(left) via a texture matrix with a scale factor and using the repeat tiling option.


Texture coordinates
===================

It is important to note that you can only apply textures to meshes which contain texture coordinates as the HOOPS Web Viewer currently does not provide any automatic texture coordinate generation functionality. This will often not be the case for imported CAD models. If you still want to apply textures to those meshes you need to generate texture coordinates yourself and replace the original mesh. See the :doc:`Meshes Programming Guide </prog_guide/viewing/geometry/meshes>` for more information.


Other considerations
====================

HOOPS Communicator also supports environment textures though those can currently only be created via the libsc authoring API or during CAD import. For more information on authoring models please see the :doc:`Authoring Programming Guide </prog_guide/data_import/authoring/data-import-stream-cache-models>` for more information.
