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.