====== Color bars and measuring sticks ======

===== Color bars and colour maps =====

False colouring is a common tool, for instance, to visualize different light absorption, temperature distribution etc. The right choice of proper colour map can make the difference between a great intuitive understandable figure or just some usual plot. GroIMP provides for this purpose the ColorGradient class, in which several common colour maps are predefined. It further supports the definition of user-defined gradients and even different interpolation methods between the colours.

The set of predefined colour maps include the following maps:

//{"hsv", "jet", "cool", "summer", "autumn", "winter", "groimp", "gray", "HEAT", "YIGNBN", "GREENS", "YIORRD", "BLUERED", "RDBU", "PICNIC", "PORTLAND", "jet2", "hot", "BLACKBODY", "EARTH", "ELECTRIC", "HARMONIC", "WEI", "WEI2", "PURPLE"}
//

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

To define a //ColorGradient// one needs to set the wanted colour map followed by a minimal and maximal value. By calling the //getColor(i)// function of the colour map, where //i// is a value within the min/max range, the associated colour is returned. The following code will produce a stack of 50 Cylinder objects, each having a different colour, reflecting the defined colour gradient - here "WEI2".

<code java>
// colour map, min, max
const ColorGradient colorMap = new ColorGradient("WEI2", 0, 50);
		
protected void init() [
  Axiom ==> 
    for(int i:(0:50)) (
      [Null(0,0.0,i*0.03) Cylinder(0.03, 0.02).(setShader(new RGBAShader(colorMap.getColor(i)))) ]
    );
]
</code>

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

Beside the predefined colour maps, user-defined sequences of colours can be used. To define a user-defined colour gradient, one need to define an array of //Colour// objects and provide it to the //ColorGradient// class.

<code java>
import java.awt.Color;

// colour map, min, max
const Color[] colors = new Color[] {Color.BLACK, Color.MAGENTA.darker(), 
  Color.decode("#cc00cc"), Color.RED.brighter(), Color.ORANGE, Color.YELLOW};
const ColorGradient colorMap = new ColorGradient(colors, 0, 50);
		
protected void init() [
  Axiom ==> 
    for(int i:(0:50)) (
      [Null(0,0.0,i*0.03) Cylinder(0.03, 0.05).(setShader(new RGBAShader(colorMap.getColor(i)))) ]
    );
]
</code>

The resulting gradient should look like this:

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


The //ColorGradient// further allows to change the interpolation method between the intermediate colours. To do so, one needs to parse a fifth parameter to the //ColorGradient// class, indicating the wanted interpolation method.

<code java>
  ColorGradient cMap_linRGB = new ColorGradient("HEAT",0,250, graphState(), 0);
  ColorGradient cMap_bSplineRGB = new ColorGradient("HEAT",0,250, graphState(), 1);
  ColorGradient cMap_bezRGB = new ColorGradient("HEAT",0,250, graphState(), 2);
  ColorGradient cMap_bSplineLab = new ColorGradient("HEAT",0,250, graphState(), 3);
  ColorGradient cMap_bezLab = new ColorGradient("HEAT",0,250, graphState(), 4);
  ColorGradient cMap_bezLabL = new ColorGradient("HEAT",0,250, graphState(), 5);
</code>

The differences between the interpolation methods are quite recognizable for the human eye. Especially the linear RGB interpolations showing recognizable gaps compared to the luminescence based La*b* colour space interpolations are very harmonic.

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


===== Measuring sticks =====

Any false colour representation without a legend as reference is not complete. GroIMP here provides a Library-function called //ColorBar// that takes the a colour map and a boolean flag indicating if the labels are turned on or off as input.

Reference objects as measuring sticks are a simple but effective tool to give the use a visual feedback to compare dimensions. GroIMP provides for this purpose a parametrizable measuring sticks - defined as function within the //Library// class.

<code java>
// HSV colour map, min, max
const ColorGradient colorMap = new ColorGradient("hsv",0,100);
		
protected void init() [
  Axiom ==> 
    [
      ColorBar(colorMap, true)// colour map, labelling
    ]
    [
      Null(0.5, 0, 0) // move 0.5m 
      MeasuringStick(10, 0.1, true) // 10 steps, 0.1m step size, labelling 
    ];
]
</code>

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