PyNGL Home > Functions > Color routines

Ngl.free_color

Removes a color entry from a workstation.

Prototype

Ngl.free_color(workstation, color_index)

Arguments

workstation

An identifier returned from calling Ngl.open_wks.

color_index

An integer scalar specifying a color index.

Return value

   None

Description

This function frees the specified color index on the specified workstation. When the color index is freed the color associated with that index is undefined and the result of any subsequent use of that index without redefining it will produce unpredictable results. All other colors and color indices except for the freed one remain unchanged. A new color can be assigned to the freed index by using either Ngl.set_color or Ngl.new_color. See the example below.

See Also

Ngl.new_color, Ngl.set_color, Ngl.get_named_color_index Ngl.draw_colormap, Ngl.retrieve_colormap,

Examples

The following script produces eight labeled color boxes showing how to free a color index and redefine it.

import Ngl
#
#  Open a workstation.
#
wks_type = "ps"
wks = Ngl.open_wks(wks_type,"free_color") 

#
#  Re-define the first nine colors in the default colormap 
#  (the rainbow colormap with 190 defined colors)
#
Ngl.set_color(wks,0,1.,0.,0.)
Ngl.set_color(wks,1,0.,1.,0.)
Ngl.set_color(wks,2,0.,0.,1.)
Ngl.set_color(wks,3,0.,1.,1.)
Ngl.set_color(wks,4,1.,0.,1.)
Ngl.set_color(wks,5,1.,1.,0.)
Ngl.set_color(wks,6,0.,0.,0.)
Ngl.set_color(wks,7,1.,0.5,0.)
Ngl.set_color(wks,8,1.,1.,1.)

#
#  Define some text resources for subsequent labels.
#
tx_res = Ngl.Resources()
tx_res.txFont = "Helvetica-Bold"
tx_res.txFontColor = 8

#
#  Free color index 2.  The color associated with this 
#  index is now undefined and index 2 is a free index.
#  All other colors and color indices remain unchanged.
#
Ngl.free_color(wks,2)

#
#  Define gray using Ngl.new_color.  This color value will
#  be assigned to the first available free color index, 
#  namely index 2 that was just freed in this case.
#
Ngl.new_color(wks, 0.8, 0.8, 0.8)

#
#  Draw and label color boxes using the first eight colors.
#  Notice that the color associated with color index 2 is 
#  now gray.
#
ci = 0
delx = 0.50
dely = 0.25
pl_res = Ngl.Resources()
for i in xrange(2):
  xl =  i*delx 
  xr = xl+delx
  for j in xrange(4):
    yb =  j*dely
    yt = yb+dely
    x = [xl,xr,xr,xl]
    y = [yb,yb,yt,yt]
    pl_res.gsFillColor = ci
    Ngl.polygon_ndc(wks,x,y,pl_res)
    Ngl.text_ndc(wks, str(ci), xl+0.5*delx, yb+0.5*dely, tx_res)
    ci = ci+1

Ngl.frame(wks)
Ngl.end()