Apply an absolute color table to an array of values.
img = act_apply(z)
z = Input 2-d array of values to color. in
STR=s Structure with absolute color table.
z = Array of tiepoint values.
h = Array of hues at tiepoints.
s = Array of saturations at tiepoints.
v = Array of values at tiepoints.
log = 1 if log, 0 if linear color table.
rgb = 1: interpolate in rgb, 0: interpolate in hsv.
abs_flag = 1 if absolute, 0 if not.
Software can use this value as a suggestion.
step_flag = 1 if stepped, 0 if smooth.
step = Step size for stepped color table.
For log color tables use 1, 2, 5, or 10.
step_offset = -0.5, 0, or 0.5 to offset step.
Assumed 0 for log color tables.
barmin = Data start range in z (def=min(z)).
barmax = Data end range in z (def=max(z)).
FILE=file Name of absolute color table file.
This is a text file in txtdb format with the same items
as in the structure above. Such a color table is built
by act_edit. Use either STR or FILE but not both.
Give the path and file name for the color table, or use
the keywords /lib_tables, /my_tables to set the path as
described below. Other flags or values may be given in
either the structure or the txtdb file and their value
accessed using val=act_info(tag).
/LIB_TABLES Assume the given color table file is in the
same directory (like IDLUSR) as this routine, act_apply.
/MY_TABLES Assume the given color table file is in the
same directory as the routine that calls act_apply.
These two keywords will add the indicated path to file
only if the given file has no path.
SLOPE=slope, OFFSET=offset Convert color table units.
These keywords allow a single color table to be displayed
in different units by converting the original table units.
Color tables are defined in terms of colors at certain
values where the values are in some units.
Unit conversion: NEW = OLD*slope + offset
Be careful mixing this conversion with the NEWRANGE keyword.
Avoid SLOPE and OFFSET with log color tables.
UNITS=units Instead of giving SLOPE and OFFSET may give
units for some color tables that have units conversions.
For example, the color table act_temp_k.txt is an
absolute color table with the following units.
Set units to one of these: 'deg C', 'deg F', 'deg K'
This allows the same color table to be applied to an
array with values in the corresponding units.
NEWRANGE=nran The original color table as given by the
FILE keyword has a data range and a display range,
may be the same but need not be (the table might
also color out of range flag values for example).
The data range covered by the color table may not be
a good match to the actual data range in the given
data array. The same color table can be remapped to
a new data range using the NEWRANGE keyword:
NEWRANGE=[data_lo, data_hi] which applies the full
color table display range to data_lo to data_hi.
To use only part of the original color table the desired
section may also be given:
NEWRANGE=[data_lo, data_hi, newmin, newmax]
which will use the colors between newmin and newmax
to color data in the range data_lo to data_hi, where
newmin and newmax refer to the original color table,
not the remapped color table.
To use the color table to autoscale the data do
NEWRANGE=[min(z),max(z)] which makes the color table
relative. The new scaling is not remembered on next
call so the original color table is not changed.
NEWRANGE=[0,0] or [0,0,0,0] does nothing.
NEWRANGE=[0,0,newmin,newmax] only sets newmin and newmax.
/CLIP clip data to color table range. If /clip is not
used then the data can use flag values outside the
range barmin to barmax if the color table extends there.
/DETAILS displays a more detailed explanation of absolute
color tables and how the NEWRANGE keyword works.
TRUE=tr Specify dimension to interleave (1, 2, or 3=def).
ERROR=err Error flag: 0=ok.
CFLAG=cflag Constant flag: 0=no, 1=yes (image is constant).
CONSTANT=const Value if constant.
img = Returned color image. out
Notes: The color table is remembered until a new one
R. Sterner, 2007 Dec 20
R. Sterner, 2008 Jan 03 --- Added NEWRANGE keyword.
R. Sterner, 2008 Jan 07 --- Allowed NEWRANGE to use partial table.
R. Sterner, 2008 Jan 15 --- Handled constant arrays.
R. Sterner, 2008 Jan 18 --- Allowed NEWRANGE to be all 0s, ignored.
R. Sterner, 2008 May 22 --- Upgraded NEWRANGE. Added /CLIP.
R. Sterner, 2008 Nov 17 --- Modified common.
R. Sterner, 2008 Nov 25 --- Adjusted step to vary as range varies.
R. Sterner, 2008 Nov 25 --- Better help text for NEWRANGE.
R. Sterner, 2008 Dec 12 --- Fixed a comment typo.
R. Sterner, 2010 Mar 22 --- Kept copy of structure in common.
R. Sterner, 2010 Apr 08 --- Forced returned image to be type byte.
R. Sterner, 2010 Apr 12 --- Fixed path & added /lib_tables, /my_tables.
R. Sterner, 2010 Apr 12 --- Fixed clipping to use barmin, barmax.
R. Sterner, 2010 Apr 13 --- Fixed the error return when no array given.
R. Sterner, 2010 May 07 --- Added keyword TRUE=tr (interleave dim).
R. Sterner, 2010 Jul 06 --- Added SLOPE=slope, OFFSET=offset for units conversion.
R. Sterner, 2010 Nov 10 --- Added support for log color tables.
R. Sterner, 2010 Nov 11 --- Made better log color table stepping.
R. Sterner, 2010 Dec 14 --- Added /DETAILS.
R. Sterner, 2010 Dec 14 --- Allowed NEWRANGE=[0,0,newmin,newmax].
R. Sterner, 2010 Dec 31 --- Added UNITS=units keyword.
R. Sterner, 2011 Jan 07 --- The no units case got broken, fixed.
Copyright (C) 2007, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.