ttools: allow colour map range restriction.

Aux and density colour maps now come with a clip config control
which allows you to select which region of the colour map to use
(by default you get it all).  In conjunction with the fairly extensive
colour map library supplied, this gives you quite a lot of control
over what colour maps you use.

topcat/src/docs/sun253.xml

@@ -18224,6 +18224,9 @@ introduced since the last version:
             Highlight Subset option.
             Also add a new Highlight Subset option in the Subsets window.</li>
         <li>Add some more colour maps.</li>
+        <li>Add clip selector for density and aux colour maps.
+            This simple measure gives you a lot more control over what
+            colour maps to use.</li>
         <li>Sky plot position formatting now honours sexagesimal setting.</li>
         </ul>
         </p></dd>

topcat/src/main/uk/ac/starlink/topcat/plot2/ShaderControl.java

@@ -39,6 +39,7 @@ public class ShaderControl extends ConfigControl {
     private static final AuxScale SCALE = AuxScale.COLOR;
     private static final ConfigKey[] SHADER_KEYS = new ConfigKey[] {
         StyleKeys.AUX_SHADER,
+        StyleKeys.AUX_SHADER_CLIP,
         StyleKeys.SHADE_LOG,
         StyleKeys.SHADE_FLIP,
         StyleKeys.SHADE_NULL_COLOR,
@@ -135,7 +136,9 @@ public ShadeAxis createShadeAxis( Range range ) {
             };
         }
         final String label = config.get( AUXLABEL_KEY );
-        final Shader shader = config.get( StyleKeys.AUX_SHADER );
+        final Shader shader =
+           StyleKeys.createShader( config, StyleKeys.AUX_SHADER,
+                                           StyleKeys.AUX_SHADER_CLIP );
         final boolean log = config.get( StyleKeys.SHADE_LOG );
         final boolean flip = config.get( StyleKeys.SHADE_FLIP );
         final Color nullColor = config.get( StyleKeys.SHADE_NULL_COLOR );

ttools/src/main/uk/ac/starlink/ttools/plot/Shaders.java

@@ -831,8 +831,9 @@ public Icon createIcon( boolean horizontal, int width, int height,
                                 int xpad, int ypad ) {
             Color baseColor = baseShader_ instanceof BasicShader
                             ? ((BasicShader) baseShader_).baseColor_
-                            : Color.BLACK;
-            return create1dIcon( this, horizontal, baseColor,
+                            : null;
+            return create1dIcon( this, horizontal,
+                                 baseColor == null ? Color.BLACK : baseColor,
                                  width, height, xpad, ypad );
         }
 

ttools/src/main/uk/ac/starlink/ttools/plot2/Subrange.java

@@ -81,4 +81,15 @@ public int hashCode() {
     public String toString() {
         return "(" + lo_ + "," + hi_ + ")";
     }
+
+    /**
+     * Indicates whether a given subrange is the identity operation,
+     * that is has no effect on a range to which it is applied.
+     *
+     * @param  subrange  subrange to test
+     * @return  true  iff subrange has values (0,1)
+     */
+    public static boolean isIdentity( Subrange subrange ) {
+        return subrange.getLow() == 0 && subrange.getHigh() == 1;
+    }
 }

ttools/src/main/uk/ac/starlink/ttools/plot2/config/StyleKeys.java

@@ -187,6 +187,10 @@ public Specifier<float[]> createSpecifier() {
         new ShaderConfigKey( new ConfigMeta( "shader", "Shader" ),
                              createAuxShaders(), Shaders.LUT_RAINBOW );
 
+    /** Config key for restricting the range of an aux shader colour map. */
+    public static final ConfigKey<Subrange> AUX_SHADER_CLIP =
+        new SubrangeConfigKey( new ConfigMeta( "shadeclip", "Shade Clip" ) );
+
     /** Config key for aux shader logarithmic flag. */
     public static final ConfigKey<Boolean> SHADE_LOG =
         new BooleanConfigKey( new ConfigMeta( "shadelog", "Shade Log" ) );
@@ -220,6 +224,10 @@ public Specifier<float[]> createSpecifier() {
                              createDensityShaders(),
                              createDensityShaders()[ 0 ] );
 
+    /** Config key for restricting the range of a density shader colour map. */
+    public static final ConfigKey<Subrange> DENSITY_SHADER_CLIP =
+        new SubrangeConfigKey( new ConfigMeta( "denseclip", "Map clip" ) );
+
     /** Config key for density shader subrange. */
     public static final ConfigKey<Subrange> DENSITY_SUBRANGE =
         new SubrangeConfigKey( new ConfigMeta( "densescale",
@@ -357,6 +365,28 @@ public static ConfigKey<String> createAxisLabelKey( String axName ) {
                                                     axName );
     }
 
+    /**
+     * Obtains a shader from a config map given appropriate keys.
+     *
+     * @param  config  config map
+     * @param  baseShaderKey   key for extracting a shader
+     * @param  clipKey   key for extracting a clip range of a shader
+     * @return  shader with clip applied if appropriate
+     */
+    public static Shader createShader( ConfigMap config,
+                                       ConfigKey<Shader> baseShaderKey,
+                                       ConfigKey<Subrange> clipKey ) {
+        Shader shader = config.get( baseShaderKey );
+        if ( shader == null ) {
+            return null;
+        }
+        Subrange clip = config.get( clipKey );
+        return Subrange.isIdentity( clip )
+             ? shader
+             : Shaders.stretch( shader,
+                                (float) clip.getLow(), (float) clip.getHigh() );
+    }
+
     /**
      * Returns an array of marker shapes.
      *

ttools/src/main/uk/ac/starlink/ttools/plot2/layer/ShapeMode.java

@@ -706,18 +706,21 @@ public ConfigKey[] getConfigKeys() {
             return new ConfigKey[] {
                 StyleKeys.COLOR,
                 StyleKeys.DENSITY_SHADER,
-                StyleKeys.DENSITY_SUBRANGE,
+                StyleKeys.DENSITY_SHADER_CLIP,
                 StyleKeys.DENSITY_LOG,
                 StyleKeys.DENSITY_FLIP,
+                StyleKeys.DENSITY_SUBRANGE,
             };
         }
 
         public Stamper createStamper( ConfigMap config ) {
             Color baseColor = config.get( StyleKeys.COLOR );
-            Shader baseShader = config.get( StyleKeys.DENSITY_SHADER );
-            Subrange subrange = config.get( StyleKeys.DENSITY_SUBRANGE );
+            Shader baseShader =
+                StyleKeys.createShader( config, StyleKeys.DENSITY_SHADER,
+                                                StyleKeys.DENSITY_SHADER_CLIP );
             boolean logFlag = config.get( StyleKeys.DENSITY_LOG );
             boolean flipFlag = config.get( StyleKeys.DENSITY_FLIP );
+            Subrange subrange = config.get( StyleKeys.DENSITY_SUBRANGE );
             Shader densityShader =
                 Shaders.applyShader( baseShader, baseColor, COLOR_MAP_SIZE );
             if ( flipFlag ) {
@@ -833,6 +836,7 @@ private static class AuxShadingMode extends ShapeMode {
         public ConfigKey[] getConfigKeys() {
             List<ConfigKey> list = new ArrayList<ConfigKey>();
             list.add( StyleKeys.AUX_SHADER );
+            list.add( StyleKeys.AUX_SHADER_CLIP );
             if ( transparent_ ) {
                 list.add( StyleKeys.AUX_OPAQUE );
             }
@@ -843,7 +847,9 @@ public ConfigKey[] getConfigKeys() {
         }
 
         public Stamper createStamper( ConfigMap config ) {
-            Shader shader = config.get( StyleKeys.AUX_SHADER );
+            Shader shader =
+                StyleKeys.createShader( config, StyleKeys.AUX_SHADER,
+                                                StyleKeys.AUX_SHADER_CLIP );
             double opaque = transparent_
                           ? config.get( StyleKeys.AUX_OPAQUE )
                           : 1;