NormalMap3
==========
:stem: latexmath
:source-highlighter: highlight.js

Keywords: normal maps

== Summary ==
This demo includes several objects that utilize tangent space normal
maps that are defined relative to the surface rather than the object's
local coordinate system. In this example, the same normal map is
applied to the sides of a wooden crate, which requires the map to be
rotated into the coordinate system relative to each side rather
than be interpreted in the coordinate system of the entire object.

== Related Materials ==
The following demos, manuals and tutorials can provide additional
information about the topics at the focus of this demo:

* Related Demos
** http://www.dirsig.org/demos/index.html#NormalMap1[NormalMap1]
** http://www.dirsig.org/demos/index.html#NormalMap2[NormalMap2]
* Related Manuals
** http://www.dirsig.org/docs/new/maps.html#NormalMap[Maps Manual]
** http://www.dirsig.org/docs/new/glist.html[GLIST Manual]
* Related Tutorials
** N/A

== Important Files ==
This section highlights key files important to the simulation.

=== The Geometry Setup
The `geometry/demo.glist` file assembles the floor, walls, crate and
barrel objects into a scene. For the tangent space normal map option
to work correctly, the tangent vector for the crate geometry should
be explicitly compiled into the scene data model used by DIRSIG.  This
tangent data is what alows the normal map to be correctly and unambigously
rotated into the plane of each side of the crate object. Requesting
the tangent data is accomplished via the explicit tangent data
http://www.dirsig.org/docs/new/glist.html#TangentData[option] in the
GLIST file:

.The GLIST configuration for the crate object.
[source,xml]
----
include::geometry/demo.glist[lines=22..39]
----

=== The Map Setup
The `Crate` material in the `demo.mat` file includes the normal map
definition.  The `Crate.obj` geometry was created with each side
of the crate using it's own UV space, meaning that the same normal
map can be applied to each side of the crate.  The normal map RGB image
is shown below.

.The RGB normal map image for the crate sides.
image::maps/WoodCrate_normal.png[width=256]

The `Crate` material in the `demo.mat` file includes the
http://www.dirsig.org/docs/new/maps.html#NormalMap[normal map]
configuration using the UV projection method with the
`SPACE = TANGENT` option:

----
include::demo.mat[lines=25..65]
----

Without the `TANGENT` space option, the normal map will be interpreted
in the object coordinate system. As a result, the RGB values in the
normal map applied to the sides would produce normals that are
generally in the +Z direction, which is in the plane of the crate
sides rather than generally normal too it. The `TANGENT` option
rotates the normal map into the tangent plane of the sides, so that
the resulting normals are generally normal to the sides of the
crate.

== Simulations and Results ==
This simulation can be run in the GUI or via the command line:
----
$ dirsig5 demo.jsim
----

Load the resulting `demo.img` radiance file in the DIRSIG
image viewer and display the RGB bands using the 2%$ and gamma = 2
range and scaling options.

.The RGB image simulation.
image::images/demo.png[]

The RGB texture image can mask the effects of the normal map. To verify the
impact of the normal map, the truth imagery can be used to visualize the
surface orientation.  The images below show the
http://www.dirsig.org/docs/new/truth.html#NormalXyz[normal] and
http://www.dirsig.org/docs/new/truth.html#ViewCosine[view angle cosine]
truth, which confirm the manipulations of the normal across the otherwise
flat sides of the crate.

.The normal truth displayed as an RGB image.
image::images/tangent_normal_truth.png[]

.The view angle cosine truth.
image::images/view_angle_truth.png[]

If the `SPACE` option in the map projector is set to `OBJECT`, the normal
map _will not_ be rotated into the coordinate system of each face, and the
derived normals will be constant across a complex object. In this case, all
the surfaces on the crate will have their normals pointing in the same
direction:

.The normal truth when using the `OBJECT` space projection.
image::images/object_normal_truth.png[]
