[Jmol-users] fully customizable color schemes

[Bob H. <ha...@st...>]

Nico, Jmol 11.3.13 is ready for release, along with Jmol 11.2.10.

The recent discussion relating to color schemes and keys gave me an 
idea. I'm happy to report that Jmol 11.3.13 introduces something we've 
wished we had for a long time: fully customizable color schemes. Several 
new features combine to make the following possible:

1) You can create a color scheme of your own and apply it to atoms, 
isosurfaces, labels, and such using the new "set userColorScheme" option.
2) You can show a color scheme array list using "show colorscheme" 
option and then use those values programmatically.
3) You can determine the color associated with a given number for a 
specific color scheme and range of values using x = n.color, where n is 
a number, and you can translate an {r g b} triple into hexadecimal 
string format [xRRGGBB] using {r g b}.color.
4) With these techniques you can create color keys that can be 
represented in the form of a set of color bars using the ECHO command to 
place them wherever on the screen you want using   color echo @x; 
background echo @x;

First -- what is a color scheme?
--------------------------------
A color scheme is a list of numbers. Each number represents a color. The 
standard Jmol uses is that of JavaScript and HTML: a 6-digit hexadecimal 
number such as [xFF0000] refers to three numbers in the range 0-255  
(0x00 to 0xFF) in the order red, green, blue. So:

[xFF0000] is red
[x00FF00] is (dark)green
[x0000FF] is blue
[xFFFF00] is yellow
[x080808] is grey

Jmol color schemes are about 30-35 color values long.

When a color scheme is applied, one also needs to specify two values -- 
minimum and maximum -- that define the range of property values that 
should be evenly spread through the color list. By default, Jmol simply 
calculates the overall minimum and maximum values for a property and 
then applies a color scheme across all those values; but you can specify 
a narrower or wider range if you like. A narrower range would result in 
"saturation" at the end of the spectrum; a wider range would result in 
not all the colors being used.


new feature: set userColorScheme [list of color names]
------------------------------------------------------

creates a color scheme referred to as "user" and its reverse, "resu"
based on a list of color values:

 set userColorScheme red green [x00FFFF] blue
 color atoms property partialcharge "user" range -1.0 1.0


new feature: show colorscheme "schemeName"
------------------------------------------
delivers "colorscheme = " followed by a string of color values.
Without the scheme name, this command returns the current colorscheme 
listing.
For example:

  show colorscheme "low"

delivers:

colorscheme = [xff0000] [xff2000] [xff4000] [xff6000] [xff8000] 
[xffa000] [xffc000] [xffe000] [xfff000] [xffff00] [xf0f000]

Example of setting an array variable to the color values:

 list = script("show colorscheme \"low\"")[15][0].split(" ")
 x = list.size # the number of colors on the list
 x = list[3] # the third color on the list
 x = list[0] # the last color on the list


new feature: .color
--------------------------------------------------------

For numbers, delivers the color associated with a given value in the 
current coloring or propertyColorScheme.
For points, translates the point {r, g, b} into the string "[xRRGGBB]"

(some number).color gives a color triple as a point {x y z}
{x y z}.color gives a hexadecimal string [xRRGGBB]


 select atomno=3;color yellow
 x = {atomno=3}.color # gives {255.0, 255.0, 0.0}
 x = {atomno=3}.color.color # gives "[xFFFF00]"

 set propertyColorScheme "bwr"
 x = {atomno=3}.partialcharge.color  # gives some {r g b} triple

These values can then be used as @x in place of a color value in other 
commands:

background @x  # color the applet background
color echo @x;background echo @x  # creates a solid box of color x  
#make a color bar


new feature: color ["schemeName"] RANGE [min] [max]
---------------------------------------------------
Allows setting of color range and scheme so that color
values can be determined. This could be used for making
a color key using positionable ECHO text boxes:

 color "bwr" absolute -0.1 0.1
 x = (0.01).color # gives the point-color associated with that number
 set echo myecho 100 100 # position
 echo "    " # just some space
 color echo @x; background echo @x  # color this bar the color of 0.01

This syntax is now also available in the ISOSURFACE command:

 isosurface molecular color "rwb" range -0.5 0.5 map MEP

is the same as

 isosurface molecular color absolute -0.5 0.5 map MEP colorscheme "rwb"

just a little more compact and consistent with the other color commands


Bleeding edge files are in 
http://chemapps.stolaf.edu/jmol/docs/examples-11/Jmol-11_3.zip

Comments, as always, are appreciated.

Bob Hanson

-- 
Robert M. Hanson
Professor of Chemistry
St. Olaf College
Northfield, MN
http://www.stolaf.edu/people/hansonr


If nature does not answer first what we want,
it is better to take what answer we get. 

-- Josiah Willard Gibbs, Lecture XXX, Monday, February 5, 1900