====== Light Sources ======

Regarding light sources, GroIMP provides a complete set of possible implementations. They all implement the //Light// and //LightBase// interfaces, which makes them easy to handle and exchange. The standard light sources are: //PointLight//, //SpotLight//, and //DirectionalLight//.


The following code places the three light sources next to each other starting with a //PointLight// on the left, a //SpotLight// in the middle, and a //DirectionalLight// on the right.

<code java>
protected void init () [
  Axiom ==> 
    [ Translate(0.0,0,0) 
      LightNode.(setLight(new PointLight())) 
      M(-0.6) TextLabel("PointLight")]
    [ Translate(0.75,0,0) 
      LightNode.(setLight(new SpotLight()))  
      M(-0.1) TextLabel("SpotLight")]
    [ Translate(1.5,0,0) 
      LightNode.(setLight(new DirectionalLight()))  
      M(-0.1) TextLabel("DirectionalLight")]
  ;
]
</code>

In the 3D View, they are visualized as a cone for a //SpotLight//, and as a single line for a //DirectionalLight//. The //PointLight// on the left has no visualization.

{{ :tutorials:light-light-node1.png?direct&400 |}}


All light sources provide the functionality of visualizing the light rays emitted by them. To do so, the visualization just need to be activated. Additionally, the number of visualized light rays and their length can be set. 

<code java>
protected void init () [
  Axiom ==> 
    LightNode.(setLight(new PointLight().(
      setVisualize(true),
      setNumberofrays(400),
      setRaylength(0.5)
    )));
]
</code>

The output of the light ray visualization of the three light sources is given below.

{{ :tutorials:light-light-node2.png?direct&400 |}}


===== PointLight =====

A //PointLight// is emitting light rays equally to all directions. 

===== SpotLight =====

As a specialization of a //PointLight//, the //SpotLight// emits only light rays within a define opening angle. 

To control the opening angle of the //SpotLight//, two functions are used: to set the inner angle, the 'core' of the spot light, the function //setInnerAngle// is used, and to set the outher angle, that describes the maximal outer, weaker radius of the spot light, the function //setOuterAngle// is used. 

<code java>
protected void init () [
  Axiom ==> 
    LightNode.(setLight(new SpotLight().(
      setInnerAngle(0.2), setOuterAngle(0.5),
      setVisualize(true),
      setNumberofrays(150),
      setRaylength(0.5)
    ))) 
  ;
]
</code>

Below, the effect of different inner and outher angles can be seen:

{{ :tutorials:spotlightangles.png?direct&600 |}}

Note: Make sure that the values for the inner angle do not extend the outer angle.

===== DirectionalLight =====

The //DirectionalLight// emits parallel light rays equally over the whole scene. It adapts its size automatically to the size of the scene. In difference to the //PointLight// and //SpotLight//, the //DirectionalLight// does not has a //setPower// function but instead a //setPowerDensity// function to define the power that should be received  by each square meter of the the scene. 

===== AreaLight =====

An area light can be created using a parallelogram as base and transforming it to a light source. It will cast a diffuse distribution in the positive direction of the local z-axis of the parallelogram. Note, as for now, it does not (yet) support user defined physical light distribution.

<code java>
module AreaLamp extends Parallelogram() {
  {
    setLight(new AreaLight().(setPower(100)));
    setLength(1); // 1m
    setAxis(0.5f, 0, 0);
  }
}
</code>

===== PhysicalLight =====

Please refer to [[tutorials:basic-spectral-light-modeling#light_sources|Spectral Light Modelling]] tutorial.


===== Light colour =====

To define the colour of the emitted light source, the function //setColor// can be used. It expectes an object of //RGBColor// type as input argument, that itself expects a triple of red, green, and blue values in the range of zero to one. E.g., to get a red light source one needs to add //setColor(new RGBColor(1,0,0))// to the list of settings for a light node.

<code java>
protected void init () [
  Axiom ==> 
    LightNode.(setLight(new SpotLight().(
      setVisualize(true),
      setNumberofrays(150),
      setRaylength(1.1),
      setColor(new RGBColor(1,0,0))
    )));
]
</code>

{{ :tutorials:light_node_colour.png?direct&400 |}}



===== Power distribution over several light sources =====

The power of all light sources implemented within GroIMP are given/set in Watt. When the light model is executed, the number of light rays is distributed no equally over all light sources, but rather relative to their power! This has the consequence that when a light source with a high power and one with a very low power are together in a scene, the physical power distribution of the light source with the lower power will be very much underrepresented.

As an example, a scene with two light sources with a power of 10W and 90W, and a total number of 10.000 rays, the first light will create 1.000 rays, the second one 9.000 rays.

{{ :tutorials:light-light-node3.png?direct&400 |}}