.. _Lighting:

================
Lights
================

Lighting Overview
----------------------------

Lighting in Omniverse Kit based apps offers a wide variety of lighting options and capabilities.  Here is a quick look at how you can expect to interact with and manage lighting.

.. raw:: html

   <div style="width: 100%;display: inline-block;position: relative;">
      <div id="dummy" style="margin-top: 56%;">
      </div>
      <div align="center">
      <div id="kaltura_player_1" style="position:absolute;top:0;left:0;left: 0;right: 0;bottom:0;border:solid thin black;"></div>
      <script type="text/javascript" src="https://cdnapisec.kaltura.com/p/2935771/embedPlaykitJs/uiconf_id/46302491"></script>
      <script type="text/javascript">
         try {
         var kalturaPlayer = KalturaPlayer.setup({
         targetId: "kaltura_player_1",
         provider:
         { partnerId: 2935771, uiConfId: 46302491 }
         });
         kalturaPlayer.loadMedia(
         {entryId: '1_nqm6gp1f'}
         );
         } catch (e)
         { console.error(e.message) }
      </script>
      </div>
   </div>


Light Sources
---------------------
Light sources in Kit based apps are made to realistically emulate real-world lights.

===========================  ===================================================================================================
Light Types                  | Real World Equivalent
===========================  ===================================================================================================
Distant Light                | Direct Sun/Moon light
Sphere Light                 | Light Bulb
Rect Light                   | Rectangular Panel Light
Disc Light                   | Circular Panel Lights and Spotlights
Cylinder Light               | Neon/Fluorescent Light Tubes
Dome Light                   | HDRI Skysphere (Background) lighting
===========================  ===================================================================================================

Distant Light
##################
Distant lights are parallel rays of light useful for showering an entire scene in a directional light.  Meant to emulate lights infinitely far away, shadows cast with type of light will be hard edged and rather harsh compared to other lights.  Ideal for Sun/Moon light, distant lights are generally a critical element to any outdoor scene.

   .. image:: /content/images/kit_lighting_distant-light.png
      :align: center
      :alt: Distant Light

Sphere Light
######################
Sphere lights emit light in all directions from a central ball (not a point).  The softness of the shadows (and overall intensity) are dictated by the radius of the central ball.  Sphere lights are effective replacements for light bulbs.

   .. image:: /content/images/kit_lighting_sphere-light.png
      :align: center
      :alt: Cylinder Light

===========================  ===================================================================================================
Light Specific Properties    | Usage
===========================  ===================================================================================================
Radius                       | Source Sphere Radius
Treat as Point               | Makes the sphere size infinitely small
===========================  ===================================================================================================

Rectangular (Rect) Light
#############################
Rectangular lights are capable of emulating light generated from a panel.  The rectangle can be adjusted in width and length to accommodate any ratio from thin rectangle to square shape.  This affect overall light power and shadow softness.

|pic1| |pic2|

.. |pic1| image:: /content/images/kit_lighting_rect-light.png
   :width: 49%

.. |pic2| image:: /content/images/rtx/104/rect-light-projector.png
   :width: 49%

===========================  ===================================================================================================
Light Specific Properties    | Usage
===========================  ===================================================================================================
Height                       | Depth of the light source (x value)
Length                       | Length of the source (y value)
Projector light type         | Enables focusing a textured light like a projector. Scale the light as desired to adjust the focus area.
===========================  ===================================================================================================

.. note:: The *Texture File* functionality is supported in |real_time_render| mode only if Sampled Direct Lighting is enabled.

Disc Light
################
Similar to the rect light the Disc light emulates panel lighting but in the shape of a circle.  Size is controlled by radius which affects overall light power as well as shadow softness. If shaping is used, the light acts as a traditional spotlight and has specialized controls to adjust the shape and color of the lights falloff.

   .. image:: /content/images/kit_lighting_disc-light.png
      :align: center
      :alt: Disc Light

===========================  ===================================================================================================
Light Specific Properties    | Usage
===========================  ===================================================================================================
Radius                       | Radius of the disc.
Focus                        | A control to shape the spread of light. Higher focus values pull light towards the center and narrow the spread.
Focus Tint                   | Off-axis color tint. This tints the emission in the falloff region. The default tint is black.
Cone Angle                   | Angular limit off the primary axis to restrict the light spread.
Cone softness                | Controls the cutoff softness for cone angle.
===========================  ===================================================================================================

.. Note:: Increasing Shadow samples per pixels in Rendering Settings smooths light falloff at the cost of render speed.

Cylinder Light
####################
Tubular lighting useful in emulating neon/fluorescent light tubes and other linear omnidirectional lighting.

   .. image:: /content/images/kit_lighting_cylinder-light.png
      :align: center
      :alt: Cylinder Light

===========================  ===================================================================================================
Light Specific Properties    | Usage
===========================  ===================================================================================================
Length                       | Width of the rectangle, in the local X axis.
Radius                       | Radius of the cylinder.
===========================  ===================================================================================================

Dome Light
#################
Used for image-based (background) lighting when supplied with a texture.  Dome lights allow you to easily light your entire scene with a high or low dynamic range image.

   .. image:: /content/images/kit_lighting_dome-light.png
      :align: center
      :alt: Dome Light

===========================  ===================================================================================================
Light Specific Properties    | Usage
===========================  ===================================================================================================
Texture File                 | A color texture to use on the dome, such as an HDR (high dynamic range) texture intended for IBL (image based lighting).
Texture Format               | Specifies the parameterization of the color map file.
                             | -automatic: Tries to determine the layout from the file itself. For example, Renderman texture files embed an explicit parameterization.
                             | -latlong: Latitude as X, longitude as Y.
                             | -mirroredBall: An image of the environment reflected in a sphere, using an implicitly orthogonal projection.
                             | -angular: Similar to mirroredBall but the radial dimension is mapped linearly to the angle, providing better sampling at the edges.
                             | -cubeMapVerticalCross: A cube map with faces laid out as a vertical cross.
===========================  ===================================================================================================

Common Light Properties
###############################

===========================  ===================================================================================================
Common Light Properties      | Usage
===========================  ===================================================================================================
Color                        | The color of emitted light, in energy-linear terms.
Enable Color Temperature     | Enables using color temperature.
Color Temperature            | Color temperature, in degrees Kelvin, representing the white point. Lower values are warmer, higher values are cooler.
Intensity                    | Scales the power of the light linearly.
Exposure                     | Scales the power of the light exponentially as a power of 2 (similar to an F-stop control over exposure).
                             | The result is multiplied against the intensity.
Normalize Power              | Normalizes power by the surface area of the light. This makes it easier to independently adjust the power
                             | and shape of the light, by causing the power to not vary with the area or angular size of the light.
Diffuse Multiplier           | A multiplier for the effect of this light on the diffuse response of materials. This is a non-physical control.
Specular Multiplier          | Adjusts the amount specularity the light contributes to.
===========================  ===================================================================================================

Light Linking
----------------------

In Omniverse, Lights can be linked to surfaces allowing individualized response to specified lights.

.. raw:: html

   <div style="width: 100%;display: inline-block;position: relative;">
      <div id="dummy" style="margin-top: 56%;">
      </div>
      <div align="center">
      <div id="kaltura_player_2" style="position:absolute;top:0;left:0;left: 0;right: 0;bottom:0;border:solid thin black;"></div>
      <script type="text/javascript" src="https://cdnapisec.kaltura.com/p/2935771/embedPlaykitJs/uiconf_id/46302491"></script>
      <script type="text/javascript">
         try {
         var kalturaPlayer = KalturaPlayer.setup({
         targetId: "kaltura_player_2",
         provider:
         { partnerId: 2935771, uiConfId: 46302491 }
         });
         kalturaPlayer.loadMedia(
         {entryId: '1_cie44swl'}
         );
         } catch (e)
         { console.error(e.message) }
      </script>
      </div>
   </div>


.. note:: Light Linking is a specific utility of Path Tracing and only works in PT Mode.

Light linking can be used when very specific control over scene lighting is needed by specifying which lights contribute illumination or shadows to an object.

Property Panel Settings
##############################

Under the Light Link and Shadow Link menus for a light, primitives can be included or excluded.  The underlying mechanism for these lists are USD collections.  The expansion
rules control how primitives are included or excluded from these collections.  **explicitOnly** links to one specific primitive, **expandPrims** includes the children of the
specified primitive, and **expandPrimsAndProperties** includes children and attributes, though attributes are not currently supported in the light linking paradigm.  The exclude
collation can act as a subtraction boolean against the include list.   If the expansion rule is set to expandPrims and the top of a hierarchy is selected as s single selection, then
the exclude list can be used to remove lower level objects from the include list.

.. image:: /content/images/lighting_light-linking-property.png

Light Link
##############################
===================================== ==========================================================================================
Option                                Result
===================================== ==========================================================================================
Light Link Include Root               On by default, this includes all objects under the root primitive              
Light Link Expansion Rule             explicitOnly, expandPrims, expandPrimsAndProperties
Light Link Includes                   *Add Target* will bring up a menu to select objects to link to the light
Light Link Excludes                   *Add Target* will bring up a menu to select objects to exclude from the light
===================================== ==========================================================================================

Shadow Link
##############################
===================================== ==========================================================================================
Option                                Result
===================================== ==========================================================================================
Shadow Link Include Root              On by default, this includes all objects under the root primitive
Shadow Link Expansion Rule            explicitOnly, expandPrims, expandPrimsAndProperties
Shadow Link Includes                  *Add Target* will bring up a menu to select objects to link to the light's shadow
Shadow Link Excludes                  *Add Target* will bring up a menu to select objects to exclude from the light's shadow
===================================== ==========================================================================================