Last modified: December 2014

URL: https://cxc.cfa.harvard.edu/chips/ahelp/add_colorbar.html
AHELP for CIAO 4.11 ChIPS v1

add_colorbar

Context: images

Synopsis

Create a colorbar for an image

Syntax

add_colorbar([id,] x, y [,imgname] [,attributes])

Color bars can also be created directly from the GUI using the
"Annotate" menu item.

Description

The function arguments.

Argument Description
id A ChipsId structure identifying the item.
x, y The location of the center of the colorbar; the plot-normalized coordinate system is used if the "coordsys" attribute is not set. The halign and valign attributes control the location of the label relative to the label text.
imgname The colorbar is associated with the current image, if any exist. This can be overridden by giving the name of the image to use, as a string.
attributes Configure object properties by giving an attribute string (a space-separated list of key=value pairs), list, dictionary, or a ChIPS object.

A colorbar displays the mapping from pixel value to color intensity. It is normally associated with an image but can be used with no image. You can also have multiple color bars for a single image.

The add_colorbar command creates a colorbar whose attributes are specified by user preferences or in an attribute list. The new colorbar becomes current by default; providing a ChipsId overrides the currency state.

Customizing the Colorbar

There are several attributes that control the colorbar characteristics. The attributes can be set to the ChIPS defaults, values provided in the add_colorbar command, or values from the user's preference file.

The attributes may also be modified with the set_colorbar command at any time; see "ahelp set_colorbar" and "ahelp setget" for more information.

Please see the section "Colorbar Preferences and Attributes" below the examples for a list of the colorbar preferences.


Examples

Example 1

chips> add_image(np.arange(25).reshape(5,5))
chips> add_colorbar(0.5, 1.05)

Adds a colorbar above the plot. It is associated with the image, so that changes to the image are automatically reflected in the colorbar: for instance after

chips> set_image(['threshold', [5,20], 'colormap', 'rainbow'])

the color bar will also change.

Example 2

chips> add_colorbar(0, 0.5, ["orientation", "vertical"])

Create a vertical colorbar at the left edge of the plot.

Example 3

chips> avals = { 'length': 0.4, 'orientation': 'vertical' }
chips> add_colorbar(0.8, 0.45, avals)
chips> set_colorbar(["width", 0.08])

Add a vertical colorbar, with height 40 per cent that of the plot, centered on the plot-normalized coordinates of (0.8,0.45). The width of the bar is then changed to 0.08.

Example 4

chips> avals = ['id', 'vert', 'orientation', 'vertical']
chips> add_colorbar(0, .5, avals)
chips> set_colorbar("label.text='chandra data'")
chips> set_colorbar("label.location=outside tick.location=inside")
chips> set_colorbar("tick.color=lime ticklabel.color=lime")
chips> c = get_colorbar()
chips> c.label.text = "nvss data"
chips> c.orientation = 1
chips> add_colorbar(1.05, .5, c)

A colorbar is created and several attributes are set. A ChipsColorBar object, "c", is created by retrieving the colorbar attributes with get_colorbar. The text and orientation are changed (0 is horizontal, 1 is vertical), then another colorbar is created to match the existing one.

Example 5

chips> from crates_contrib.images import imextent
chips> img1 = np.arange(50).reshape(5, 10)
chips> img2 = np.arange(50).reshape(10, 5)
chips> tr1 = imextent(img1, 100, 200, 75, 125, limits='edge')
chips> tr2 = imextent(img2, -40, 40, 0, 200, limits='edge')
chips> clear()
chips> add_image(img1, tr1)
chips> add_image(img2, tr2)
chips> limits(-50, 250, -50, 250)
chips> set_image(['colormap', 'rainbow'])
chips> set_image('image1', ['colormap', 'hsv', 'invert_colormap', True])
chips> avals = {'coordsys': DATA, 'length': 10, 'width': 1}
chips> add_colorbar(150, 200, "image1", avals)
chips> avals['length'] = 5
chips> add_colorbar(0, -20, "image2", avals)

In this example we use the imextent routine to create the transformations needed to display img1 (a 10 by 5 image) over the axis ranges x=100 to 200 and y=75 to 125, and img2 (a 5 by 10 image) over x=-40 to 40 and y=0 to 200. Different colormaps are applied to the two images, which are displayed in the same plot.

When adding the color bars we explicitly include, in the add_colorbar call, the name of the image the bar is to be associated with (since we did not specify them in the add_image calls then they default to 'image1' and 'image2'). The color bars are placed in data units, hence the need for setting the 'coordsys' attribute.

Note that the length and width units are actually in logical units (i.e. the number of pixels in the image) rather than data coordinates.


Colorbar Preferences and Attributes

The attributes associated with colorbars are given in the following table, where the "Set?" column refers to whether the attribute can be changed using the set_colorbar() command. To change the colorbar preference settings prepend "colorbar." to the attribute name.

Attribute Description Options Default Set?
border.visible should the border of the colorbar be visible? see the Booleans section of "ahelp chipsopt" true Yes
depth the depth of the colorbar see the Depth section of "ahelp chipsopt" default Yes
halign horizontal alignment of the colorbar auto|base|center|left|right|top; see the Text Alignment section of "ahelp chipsopt" center Yes
label.angle angle, in degrees, of the label -360.0 to 360.0 0 Yes
label.color color of the label name or hex; see the Color section of "ahelp chipsopt" default Yes
label.font font for the label helvetica|courier|times|greek; see the Font section of "ahelp chipsopt" helvetica Yes
label.fontstyle style for the label normal|bold|italic|bolditalic; see the Font Style section of "ahelp chipsopt" normal Yes
label.halign horizontal alignment of the label auto|base|center|left|right|top; see the Text Alignment section of "ahelp chipsopt" auto Yes
label.location which side of the colorbar does the label appear on, relative to the plot center? outside|inside inside Yes
label.size size of the label 1 to 100 12 Yes
label.text text for the colorbar label Yes
label.valign vertical alignment of the label auto|base|center|left|right|top; see the Text Alignment section of "ahelp chipsopt" auto Yes
label.visible should the label be visible? see the Booleans section of "ahelp chipsopt" true Yes
length the length of the colorbar, in plot-normalized coordinates A real number, greater than 0. 1 Yes
offset.parallel shift of the label from the center of the colorbar -0.5 to 0.5 inclusive; 0 is the center and -0.5/+0.5 refer to the edges 0 Yes
offset.perpendicular shift of the label from the edge of the colorbar (in pixels) -100 to 100, inclusive 5 Yes
orientation orientation of the colorbar "horizontal" or "vertical" horizontal Yes
stem stem to use for colorbar ids An alpha-numeric character sequence that does not contain a space cbar No
tick.color color of the tickmarks name or hex; see the Color section of "ahelp chipsopt" default Yes
tick.length length of the tickmarks Non-negative integer 4 Yes
tick.location should the ticks and labels appear on the outside or inside of the colorbar with reference to plot center? inside|outside outside Yes
tick.mode mode for calculating tickmark locations arbitrary|count|interval|limits|nice; see the Tick Mode section of "ahelp chipsopt" nice Yes
tick.style should the tickmarks extend into the colorbar, point out of the colorbar, or both (inside, outside, or centered)? inside|outside|centered; see the Tick Style section of "ahelp chipsopt" inside Yes
tick.thickness thickness of the tickmarks 0.5 to 10.0; see the Thickness section of "ahelp chipsopt" 1 Yes
tick.visible should the tickmarks be visible? see the Booleans section of "ahelp chipsopt" true Yes
ticklabel.angle angle, in degrees, of the tickmark labels -360.0 to 360.0 0 Yes
ticklabel.color color for the numeric tickmark labels name or hex; see the Color section of "ahelp chipsopt" default Yes
ticklabel.font font for the tickmark labels helvetica|courier|times|greek; see the Font section of "ahelp chipsopt" helvetica Yes
ticklabel.fontstyle style for the tickmark labels normal|bold|italic|bolditalic; see the Font Style section of "ahelp chipsopt" normal Yes
ticklabel.halign horizontal alignment of the tickmark labels auto|base|center|left|right|top; see the Text Alignment section of "ahelp chipsopt" auto Yes
ticklabel.offset separation, in pixels, of the tickmark labels from the colorbar Non-negative value 6 Yes
ticklabel.size font size of the numeric tickmark labels 1 to 100 12 Yes
ticklabel.valign vertical alignment of the tickmark labels auto|base|center|left|right|top; see the Text Alignment section of "ahelp chipsopt" auto Yes
ticklabel.visible should the tickmark labels be visible? see the Booleans section of "ahelp chipsopt" true Yes
valign vertical alignment of the colorbar auto|base|center|left|right|top; see the Text Alignment section of "ahelp chipsopt" center Yes
width the width of the colorbar, in plot-normalized coordinates Non-negative value 0.05 Yes

Bugs

Using data coordinates

When using data coordinates to place a colorbar, the length and width attributes are always in logical coordinates (i.e. the number of pixels along the X and Y axes), even if a coordinate transform, such as a WCS tangent-plane projection, is being used to display the image.

See the bugs pages on the ChIPS website for an up-to-date listing of known bugs.

See Also

chips
chips, chipsgui, chipsrc, show_gui
concepts
aspectratio, attributes, chipsid, chipsopt, colors, coordsys, currency, depthcontrol, entitycreation, preferences, setget
images
current_colorbar, delete_colorbar, display_colorbar, get_colorbar, hide_colorbar, move_colorbar, set_colorbar, shuffle_colorbar