rimcursor: Read the image display cursor (makes a list)

Package: lists

Usage

rimcursor [image]

Parameters

image: The name of the reference image to which coordinates should refer. This parameter will be queried only if rimcursor cannot obtain the reference image name by other means; e.g. when cursor reads are being performed using the image display, rimcursor will assume that image is the currently displayed image.

wcs = "logical"

The world coordinate system (wcs) to be used for coordinate output. The following standard world systems are predefined.

logical: Logical coordinates are image pixel coordinates relative to the image currently being displayed. This is what the raw cursor read returns, so by default, rimcursor merely passes back the raw image cursor coordinates as would be returned by "=imcur".

physical: The physical coordinate system is invariant with respect to linear transformations of the physical image matrix. For example, if the reference image was created by extracting a section of another image, the physical coordinates of an object in the reference image will be the pixel coordinates of the same object in the original image. The physical coordinate system thus provides a consistent coordinate system (a given object always has the same coordinates) for all images, regardless of whether any user world coordinate systems have been defined.

world: The "world" coordinate system is the current default WCS. The default world system is the system named by the environment variable defwcs if defined in the user environment and present in the reference image WCS description, else it is the first user WCS defined for the image (if any), else physical coordinates are returned.

In addition to these three reserved WCS names, the name of any user WCS defined for the reference image may be given. A user world coordinate system may be any linear or nonlinear world system.

wxformat = "", wyformat = "": The default output format for the x and y coordinates. If wxformat or wyformat are undefined, rimcursor uses formatting options stored with the WCS in the image header. If the WCS formatting options are not defined in the image header, then rimcursor uses a default format.

cursor = "": The source for image cursor input. By default, the hardware image cursor is read.

Description

The task rimcursor iteratively reads the image display cursor, writing the cursor values to the standard output. The standard output may be redirected into a text file to generate a coordinate list for use as input to other tasks. Any IRAF program which normally reads the image cursor interactively may be run taking input from a list prepared using rimcursor.

An image should be displayed on the image display device before running rimcursor, and the device set to display the desired frame. When the program is run, a loop is entered reading the image cursor until the end of file character (e.g., <ctrl/d> or <ctrl/z>) is typed. Each cursor read causes a line to be printed on the standard output, after which the cursor is again read. Cursor values consist of two coordinates, a coordinate system identification (currently identifying the display frame), and the key or colon command typed to terminate the cursor read. Note this task does not return pixel value information, see imexamine for this purpose.

While the program is waiting for the cursor to be read, i.e. whenever the image cursor is blinking rapidly, the terminal is said to be in "cursor mode". To read the cursor position, enter any key not recognized as a cursor mode command (currently there are no cursor mode commands for the image cursor so any character may be typed). The colon key returns to text input for a line of text terminated by a carriage return. This is called a "colon command". The actual character or colon command one types depends upon the program for which the list is intended. If the program will use only the coordinates of the cursor any character may be typed, e.g., the space bar. If the program uses the key value to determine what action to take, then you must type a specific key.

The X and Y coordinates of the cursor position and other information comprising the cursor value are printed on the standard output when the cursor is read. To keep track of objects or features marked in a long set of cursor reads one may want to enable display marking if provided by the display device; e.g. the imtool display server. Other useful features, such as zoom, may be available in the display device also.

The coordinates returned by rimcursor depend on the type of world coordinate system chosen by parameter wcs and those defined by the reference image. The default "logical" coordinates are the image pixel coordinates being displayed. This is available for all images and may be required by other tasks which read the generated list. The "physical" coordinate system provides coordinates from the "original data image" irrespective of any linear transformations (such as image sections) used to generate the current image from the original data image. Coordinates in a user or application defined linear or nonlinear world coordinate system may be obtained by setting the wcs parameter to "world" for coordinate output in the default world system, or to the name of the specific world system for which coordinates are desired. An example of a world coordinate system for direct astronomical images is RA and DEC using the tangent (gnonomic) projection.

Coordinate transformations from the logical coordinates of image pixels as given by a raw image cursor read, to physical or world coordinates is performed by rimcursor. This aspect of the task may be used to transform image pixel coordinate lists of x and y values, as produced by some tasks such as apphot or daophot into world coordinates by specifying cursor input from the file rather than the image display cursor.

Formats

A format specification has the form "%w.dCn", where w is the field width, d is the number of decimal places or the number of digits of precision, C is the format code, and n is radix character for format code "r" only. The w and d fields are optional. The format codes C are as follows:

b       boolean (YES or NO)
c       single character (c or '\c' or '\0nnn')
d       decimal integer
e       exponential format (D specifies the precision)
f       fixed format (D specifies the number of decimal places)
g       general format (D specifies the precision)
h       hms format (hh:mm:ss.ss, D = no. decimal places)
m       minutes, seconds (or hours, minutes) (mm:ss.ss)
o       octal integer
rN      convert integer in any radix N
s       string (D field specifies max chars to print)
t       advance To column given as field W
u       unsigned decimal integer
w       output the number of spaces given by field W
x       hexadecimal integer
z       complex format (r,r) (D = precision)

Conventions for w (field width) specification:

    W =  n      right justify in field of N characters, blank fill
        -n      left justify in field of N characters, blank fill
        0n      zero fill at left (only if right justified)
absent, 0       use as much space as needed (D field sets precision)

Escape sequences (e.g. "\n" for newline):

\b      backspace   (not implemented)
     formfeed
\n      newline (crlf)
\r      carriage return
\t      tab
\"      string delimiter character
\'      character constant delimiter character
\\      backslash character
\nnn    octal value of character

Examples

%s          format a string using as much space as required
%-10s       left justify a string in a field of 10 characters
%-10.10s    left justify and truncate a string in a field of 10 characters
%10s        right justify a string in a field of 10 characters
%10.10s     right justify and truncate a string in a field of 10 characters

%7.3f       print a real number right justified in floating point format
%-7.3f      same as above but left justified
%15.7e      print a real number right justified in exponential format
%-15.7e     same as above but left justified
%12.5g      print a real number right justified in general format
%-12.5g     same as above but left justified

%h          format as nn:nn:nn.n
%15h        right justify nn:nn:nn.n in field of 15 characters
%-15h       left justify nn:nn:nn.n in a field of 15 characters
%12.2h      right justify nn:nn:nn.nn
%-12.2h     left justify nn:nn:nn.nn

%H          / by 15 and format as nn:nn:nn.n
%15H        / by 15 and right justify nn:nn:nn.n in field of 15 characters
%-15H       / by 15 and left justify nn:nn:nn.n in field of 15 characters
%12.2H      / by 15 and right justify nn:nn:nn.nn
%-12.2H     / by 15 and left justify nn:nn:nn.nn

\n          insert a newline

Examples

1. Interactively generate a starlist (file "starlist") to be used as input to another program, e.g., for digital photometry.

cl> display dev$pix 1       # display image in frame 1
cl> rimcursor > starlist    # make the object list

At this point, the cursor loop is entered and the terminal
is placed into cursor mode.  The positions are marked using
the space bar.

space_bar           mark the position of the object
space_bar           mark the position of another object

<ctrl/z>            (EOF) terminates rimcursor

Given the above command sequence, the output file "starlist" might contain the following cursor values.

441. 410. 101 \040
208. 506. 101 \040
378. 68. 101 \040

2. Get world coordinates for the default world coordinate system.

cl> rimcur wcs=world
12.13436 63.5565 101 \040
12.13448 63.5529 101 \040
12.13499 63.5588 101 \040

Since there is no format information in the image header, the coordinates are decimal RA and DEC in degrees.

3. Output the RA and DEC coordinates for an image in sexagesimal degrees.

cl> rimcur wcs=world xformat=%12.2h yformat=%12.2h
19:47:12.25 33:15:03.66
19:43:12.10 33:14:38.06
19:45:12.40 33:15:56.03

4. Output the RA in sexagesimal hours and DEC in sexagesimal degrees for an image.

cl> rimcur wcs=world xformat=%12.2H yformat=%12.2h
13:47:12.25 47:15:03.66
13:47:12.10 47:15:38.06
13:47:12.40 47:15:56.03

5. Convert a list of pixel coordinates to world coordinates.

cl> rimcur obs001 wcs=world cursor=coordlist >worldlist

Notes

Future plans call for implementation of cursor mode commands for image display cursors similar to those available for graphics cursors.