NAME:		harwell

AUTHOR INFO:	Kevin White, Stardent Computer Ltd.
    Ver. 2:     Ian Curington, AVS Inc.

SOURCE FILE:	harwell.c

TYPE:		data_input

INPUTS:		NONE

OUTPUTS:	colormap

PARAMETERS:     Name		Type	Default		Min	Max 
		Gamma		float	 1.4		0.	5.
		blue c/o	float	 0.3		0.	1.
		green c/o	float	 0.45		0.	1.
		red c/o		float	 0.67		0.	1.
		Range Mode	choice   continuous     continuous/stair-step
		No. of Steps	int	 16		2	64
      (new)     low             float    0.  colour range for mapping
      (new)     high            float    0.  colour range for mapping
      (new)     n-regions       choice   3-region, blue-red, black-white
      (new)     mark end bins   toggle   define out of range colours
      (new)     mark stair steps toggle  black lines at transitions 

DESCRIPTION:
	Harwell is a color map generator. It provides an algorithm defined
color set. It is gamma corrected, and has three distinct regions,
with linear interpolation between the regions. The colourmap is
stair-stepped, with user controlled number of steps, and will optionally
mark the first and last entry with a distinct colour so out-of-range
data will be marked. It can also mark each step with a black line.
It has build-in patterns for rainbow, blue-red, black-white,
blue-white, blue-yellow, red-yellow-white (heat) color tables.


Notes:

The regions are

   blue --> green --> yellow --> red
           or
   blue --> red
           or
   black --> white

The cutoff points are controlled by the three float dial parameters.
The gamma is also adjustable. The default values are designed
for the "standard fringe".

This module can be used anywhere "generate colormap" can be used.

As it does not have an interactive color window widget, you can
see the colormap by wiring the output of this into the parameter
port of "generate colormap" by making the port visible,
or with "field legend".

An optional mode creates a "stair step" color map, with integer
step transitions between color regions. The steps are uniform,
but the color assignments still use the analytic transfer function.
The number of steps are controlled by the No. of Steps dial.

The choice selector switches between continous smooth fringe ramp,
and the stair step mode.
In stair-step mode, the 1st entry will be blue, and to last red.
For only 2 steps, these are the only colours, with the break point
in the center of the colormap.

Strange results will result if the color cutoff points are set
non-monotionic. For instance if the blue c/o is at a higher value
than the green c/o, a discontinuity will result. There is no 
bug here, If you like what you see, go ahead and use it!


Version 2 implementation notes:
 [12 March 92 Ian Curington ]
 fixed bad includes,
 removed statics from function definitions
 fixed double-float param problem
 removed local stack storage for output structure,
  put in malloc so AVS can manage memory free,
 removed casts to void
 fixed bug on invalid default on choice list (core dump on DEC)
 re-organized user interface.
 renamed files for < 14char length
 updated man page
 

BUG NOTE:

Forwarded message:
> From jacque Wed Apr 13 15:19 EDT 1994
> Date: Wed, 13 Apr 94 15:19:41 EDT
> From: jacque (Jacqueline Caldwell)
> Message-Id: <9404131919.AA01863@phobos.avs.com>
> To: alexy, billc, davek, davids, gavin, ham, jjv, joe, jts, kaz, larryg, lbm,
>         lour, mike, rjm, stardent_bugrs, tasos
> Subject: Fixed by jacque: 10706
> 
	:
	:
	:
> 
> As an aside, I also have problems with the Harwell Colormap module.
>  
> "Hammering" the module will ALWAYS cause a network to hang (my words: mind
> you, I have seen memory problems with the standard GENERATE COLORMAP on
> Unix systems if you "doodle" within the colormap too often and for too
> long).
>  
> The problem is in the code (my words: do we want to pass this bit on
> to the IAC ?)
>  
> The module uses:
>  
>    colormap_compute (output, parameter)
>       AVScolormap **output;
>       int parameter;
>       {
>          static AVScolormap map;
>          float hue[BYTE_TABLE];
>          ...
>          /* make other components */
>          map.hue = hue;
>          ...
>          /* build the colormap */
>          *output = &map;               <--- ***** BAD LINE *****
>          return;
>       }
>  
> When you work the module too hard, 'map' is destroyed so the pointer
> *output now points to an invalid address. AVS reports an access violation
> and hangs. (my words: he has fixed this by using AVSdata_alloc()).
>  
> This is VERY similar to the problems I get with my own networks which
> include my OWN modules. I get access violations about 5% of the time.
> (my words: I reported this some time ago, but as he can't get the debugger
> working then he can't find out what is wrong!!)
>  
> Hope this will help in the release of 5.01 on OpenVMS.
>  
> Let me know if you need any more info on these.