======
Images
======

An *image* is a 2D array of pixels. Images are like markers and annotation text in that they are always drawn in screen space (if you want to see an image rotate in 3D, you would apply it as a texture to a 3d object by using HOOPS/3dGS' :doc:`texture mapping </prog_guide/3dgs/05_2_materials_texture>` support). The following program creates and display a simple image: a set of eight color bars.

.. tabs::

	.. group-tab:: C++
	
		.. literalinclude:: ../../../../hoops_3df/demo/common/sanity/0700_docs_0015.cpp
		   :start-after: //! [color_bars]
		   :end-before: //! [color_bars]
		   
*Color bars created with an RGB image.*

In the code above, each pixel was defined as an RGB value, with 3 bytes taken up in the image array for each pixel. An alternative way to define an image is to use color indices into a color map. Below, each pixel only needs 1 byte in the image array. Each byte in the image array is an index into the local color map. The local color map is set on line 8. Note that a color map is an attribute in HOOPS, so different segments can have different color maps. 

.. tabs::

	.. group-tab:: C++
	
		.. literalinclude:: ../../../../hoops_3df/demo/common/sanity/0700_docs_0015.cpp
		   :start-after: //! [color_map]
		   :end-before: //! [color_map]
		   
*Color bars created with a mapped image.*

Of course, color bars are not a particularly interesting image. In fact, it probably would be better for us to define color bars using a mesh, or at least as eight polygons. The problem with using an image is that the appearance of an image is platform dependent, because images are defined in screen space (one image pixel per screen pixel). An image will appear larger or smaller depending on the resolution of the display. On a device with a very high resolution, such as a printer, an image will appear very small. 
  
You can retrieve the data from an image using the ``Show_Image`` command. You can also determine the size, format, and location of an image using the ``Show_Image_Size`` command. You can edit the individual pixels in an image using the ``Edit_Image`` command. See the HOOPS/3dGS Reference Manual for more information. To update an image's name, size as well as other options specified in the format parameter of ``Insert_Image``, you can use ``Edit_Image_Options``.
  
HOOPS also supports the importation of compressed images via the ``Insert_Compressed_Image`` function.  The following compressed image formats are supported:

* JPEG
* TGA
* DXT1
* DXT3
* DXT5

A more common use of HOOPS images is to display externally generated images. HOOPS can display images that either are in raw bitmap form, or use indices into a color map. Most externally generated images, however, use some sort of compression to reduce storage requirements. For example, images are often stored in GIF or JPEG format. The HOOPS/MVO classes provide several built-in image conversion functions, and also provide comprehensive image I/O support via the integration with the LeadTools image conversion toolkit.


Images as attributes
====================

An image is normally considered to be geometry, but an image can be also used as an attribute. For example, an image can be used as the basis for a texture to modify the appearance of the faces of shells or meshes. The :doc:`texture section </prog_guide/3dgs/05_2_materials_texture>` contains information on how to use an image as a color or as a texture map.
  

Scalable images
===============

HOOPS/3dGS supports scaling of images. There are 2 ways to use this feature:

1. A linear image scaling factor can be set which will inherit down the tree like any attribute. This is set by using the "image scale" rendering option:

.. tabs::

	.. group-tab:: C++
	
		.. literalinclude:: ../../../../hoops_3df/demo/common/sanity/0700_docs_0015.cpp
		   :start-after: //! [image_scale]
		   :end-before: //! [image_scale]
		   
2. An image can be scaled on an individual basis by using the "size" format option of Insert_Image. This option can be set in two ways. You can independently set the width/height components:

.. tabs::

	.. group-tab:: C++
	
		.. literalinclude:: ../../../../hoops_3df/demo/common/sanity/0700_docs_0015.cpp
		   :start-after: //! [image_size]
		   :end-before: //! [image_size]

If the image is 100x200 pixels and 0.1 oru happens to be 50 pixels, then the above setting will produce an image size of 50x50 pixels. (Aspect ratio is not maintained.) 
  
Or, you can just set the "size" option alone:

.. tabs::

	.. group-tab:: C++
	
		.. literalinclude:: ../../../../hoops_3df/demo/common/sanity/0700_docs_0015.cpp
		   :start-after: //! [image_oru]
		   :end-before: //! [image_oru]
		   
If the image is 100x200 pixels and 0.1 oru happens to be 50 pixels, then the above setting will produce an image size of 25x50 pixels. (Aspect ratio is maintained.)
