Chandra X-Ray Observatory
Skip to the navigation links
Last modified: November 2016

Jump to: Description · Examples · Bugs · See Also

AHELP for CIAO 4.9 ChIPS v1


Context: coordinates


Return the coordinates of one or more mouse or key presses.


get_pick(count, eventmask)
get_pick(id, count)
get_pick(id, count, eventmask)


The function arguments.

Argument Description
count The number of events to capture; default is 1.
eventmask Which type of events to capture (the default is taken from the pick.mask preference setting).
id A ChipsId structure identifying the item.

The get_pick command allows the user to obtain the location of the cursor when a specified event is registered.

Valid event types for the eventmask argument:

Event type Numeric value Description
KEY_PRESS 0x01 pressing any key
KEY_RELEASE 0x10 releasing any key
BTNS_DOWN 0x0E clicking any mouse button
BTN1_DOWN 0x02 clicking the left mouse button
BTN2_DOWN 0x04 clicking the middle mouse button
BTN3_DOWN 0x08 clicking the right mouse button
BTNS_UP 0xE0 releasing any mouse button
BTN1_UP 0x20 releasing the left mouse button
BTN2_UP 0x40 releasing the middle mouse button
BTN3_UP 0x80 releasing the right mouse button

The default eventmask value is "KEY_PRESS|BTNS_DOWN"; this can be changed by setting the pick.mask preference. Note that when more than one entry is specified, they are joined via the | (vertical pipe) symbol.

The following coordinate systems may be used to display the cursor location - PIXEL, FRAME_NORM, PLOT_NORM, or DATA. The system is specified by setting the coord_sys field of the optional ChipsId structure. If not specified, the coordinates are returned in the current coordinate system for the window. The command will only work if a single window is current.

When an event is registered, the coordinates are stored internally as a (x,y) coordinate pair. The get_pick command returns an array of x positions, an array of y positions, and an array of numeric values representing the type of event. If any of the events were key presses or releases, a fourth array of the respective key values is also returned. The values of these events are given in the table above.

Coordinate format

Two string arrays contain the coordinate values using the formatting of the axes. So, if the X axis has a tickformat attribute of "%ra" then the X coordinate will be returned as both a floating-point value and a string that looks like "14:58:20".

Number of events

The number of events to capture may be set by the user via the count parameter; the default value is 1. A value of 0 indicates that the pick should continue until the user uses the escape key (<ESC>) to end the pick. A count value greater than 0 indicates that the pick should continue until the specified number of events has occurred.

To have the coordinates of the pick points printed to the screen instead of being stored in an array, use the pick command ("ahelp pick").

Example 1

chips> clear()
chips> add_curve([1,2,5], [-9,14,5])
chips> a = get_pick()
chips> print("x = {0} y = {1}".format(a[0][0], a[1][0]))
x = 2.8403 y = -5.31489

Retrieve the coordinates of a single point. The return value from get_pick() is an array of 5 or 6 items. In this case, since the event was a mouse press (the value of a[2][0] is 2 which is the value of BTN1_DOWN), there are only five items (the last two give the string representation of the coordinate, using the axis formatting):

chips> a
[array([ 1.90162964]),
 array([2], dtype=uint32),

The a[0] and a[1] elements contain the X and Y coordinates of the events (in this case there is only 1).

Example 2

chips> clear()
chips> add_image("img.fits")
chips> set_xaxis(["tickformat", "%ra"])
chips> set_yaxis(["tickformat", "%dec"])
chips> a = get_pick()
chips> print("x = {} y = {}".format(a[0][0], a[1][0]))
x = 239.559788796 y = 27.2730363564
chips> print("ra = {} dec = {}".format(a[3][0], a[4][0]))
ra = 15:58:14 dec = +27:16:23

Here we display an image and use sexagesimal notation for the coordinates. In this case the last two elements returned by get_pick() contain the coordinates using this notation.

chips> a

[array([ 239.5597888]),
 array([ 27.27303636]),
 array([2], dtype=uint32),

Example 3

chips> id = ChipsId()
chips> id.coord_sys = FRAME_NORM
chips> a = get_pick(id)

Retrieve the frame normalized location of a point, using the default eventmask.

Example 4

chips> id = ChipsId()
chips> id.coord_sys = DATA
chips> a = get_pick(id, 0, BTN3_DOWN)

Retrieve the cursor location in data coordinates whenever the right mouse button is pressed, until the Escape key is pressed. If

chips> a = get_pick(id, 0, KEY_PRESS)

had been used instead then the location would be recorded whenever a key was pressed instead (the Escape key is not considered a key press in this context; it exits the pick call instead).

Example 5

chips> a = get_pick(3, BTN3_DOWN)
chips> a[0]
array([-4.01444456, 4.78555553, 9.9677778 ])
chips> a[1]
array([ 0.95510914, -0.57461505, -1.40901007])
chips> a[2]
array([1, 1, 2], dtype=uint32)
chips> a[2] == KEY_PRESS
array([ True, True, False], dtype=bool)
chips> a[2] == BTN1_DOWN
array([False, False, True], dtype=bool)
chips> print(a[3])
['w' 'g' '']

Here we use get_pick to select three coordinates, using either key presses or mouse button events to select the positions. The first two positions were selected using key presses - using the "w" and "g" keys respectively - whilst the third was selected using the left-mouse button.


The button event types are not processed correctly

The button-up event types - such as BTNS_UP and BTN1_UP - are not handled correctly and should not be used. The button-down evens - such as BTNS_DOWN - may also incorrcetly register up events; this may mean duplicated positions are returned.

Do not use when the window display is turned off

It is possible to hang ChIPS if you use get_pick with a window which was created with its display attribute set to False and this attribute has remained unchanged.

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

See Also


Last modified: November 2016
Smithsonian Institute Smithsonian Institute

The Chandra X-Ray Center (CXC) is operated for NASA by the Smithsonian Astrophysical Observatory. 60 Garden Street, Cambridge, MA 02138 USA.   Email: Smithsonian Institution, Copyright © 1998-2017. All rights reserved.